Rotate API Key

Beta

POST/v1/auth/api-keys/{id}/actions/rotate

Idempotent with Idempotency-Key header. Learn more

Rotates an API key by revoking the existing key and issuing a replacement with the same name, role, and expiration. The new secret is returned once.

idstring

API key ID to rotate.

include[]optional arrayenumValues:rolerole.permissions

Sub-objects to expand in the response. When omitted, sub-objects are returned as null.

expires_atoptional string (date-time)

Expiration time override.

api_key_secretstring

Full secret value. Returned once and cannot be retrieved later.

api_key_infoobject

API key metadata.

idstring

API key ID.

objectstringenumValues:api_key

Resource type identifier.

namestring

Human-readable name for the API key.

redacted_valuestring

Redacted key value.

roleobjectExpandablenullable

Assigned role.

idstring

Role ID.

objectstringenumValues:role

Resource type identifier.

namestring

Display name.

typestringenumValues:adminuserscanner

Role type code.

ownerobjectnullable

Owner of this resource.

Always returned as null in this endpoint.

permissionsarray of stringExpandablenullable

Permissions in {domain}:{action} format.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

last_used_atstring (date-time)nullable

Last used timestamp.

expires_atstring (date-time)nullable

Expiration timestamp.

revoked_atstring (date-time)nullable

Revocation timestamp.

Responses

201

Successful response for Rotate API Key

Rotate API Key

curl API_HOST/v1/auth/api-keys/{id}/actions/rotate \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: 1.0.forge-preview.1" \
  -H "Content-Type: application/json" \
  -d '{
  "expires_at": "2026-12-31T23:59:59Z"
}'

curl API_HOST/v1/auth/api-keys/{id}/actions/rotate \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Augno-Version: 1.0.forge-preview.1" \
  -H "Content-Type: application/json" \
  -d '{
  "expires_at": "2026-12-31T23:59:59Z"
}'

201 example

{
  "api_key_secret": "aug_sk_prod_RhxFDvTdDnb0bgtcoA5P79_60EmH4h9j9ZldsuU9XyngXlpu8NqdIlGTQw8OM8cGeCadyhjtr",
  "api_key_info": {
    "id": "apke_01jm4r6700e3kxb9w2nqh7g5fp",
    "object": "api_key",
    "name": "Production API Key",
    "redacted_value": "aug_sk_prod_****hjt4",
    "role": {
      "id": "rl_01gf7a8200er3ar3pkfrb6kk29",
      "object": "role",
      "name": "Admin",
      "type": "admin",
      "owner": null,
      "permissions": [
        "customers:create",
        "customers:read",
        "customers:update",
        "customers:delete"
      ],
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    },
    "created_at": "2026-05-10T00:00:00Z",
    "updated_at": "2026-05-10T00:23:00Z",
    "last_used_at": "2026-05-10T00:23:00Z",
    "expires_at": "2026-06-10T00:00:00Z",
    "revoked_at": null
  }
}

{
  "api_key_secret": "aug_sk_prod_RhxFDvTdDnb0bgtcoA5P79_60EmH4h9j9ZldsuU9XyngXlpu8NqdIlGTQw8OM8cGeCadyhjtr",
  "api_key_info": {
    "id": "apke_01jm4r6700e3kxb9w2nqh7g5fp",
    "object": "api_key",
    "name": "Production API Key",
    "redacted_value": "aug_sk_prod_****hjt4",
    "role": {
      "id": "rl_01gf7a8200er3ar3pkfrb6kk29",
      "object": "role",
      "name": "Admin",
      "type": "admin",
      "owner": null,
      "permissions": [
        "customers:create",
        "customers:read",
        "customers:update",
        "customers:delete"
      ],
      "created_at": "2026-05-10T00:00:00Z",
      "updated_at": "2026-05-10T00:23:00Z"
    },
    "created_at": "2026-05-10T00:00:00Z",
    "updated_at": "2026-05-10T00:23:00Z",
    "last_used_at": "2026-05-10T00:23:00Z",
    "expires_at": "2026-06-10T00:00:00Z",
    "revoked_at": null
  }
}

Rotate API Key

Path Parameters

Query Parameters

Request Body

Returns

Responses