> ## Documentation Index > Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt > Use this file to discover all available pages before exploring further. # Rotate an API key > Generates a replacement key and transitions the existing key into a grace period. The old key remains usable until its grace period expires, giving you time to deploy the new value before the old one stops working. The new key's full value is returned in this response and never again — store it immediately. The grace period defaults to 24 hours. Set `grace_period_hours` to any value between 1 and 168 (7 days). The grace period cannot extend past the old key's configured expiry time. ## OpenAPI ````yaml /openapi/api_keys.yaml post /keys/{id}/rotate openapi: 3.0.3 info: title: Ionic API Keys API version: '2026-05-01' description: > API keys — the authentication credentials for the Ionic API. A standard secret key (`sk_…`) is a server-side-only credential whose data-plane permissions follow Ionic's current standard policy. A restricted secret (`rk_…`) carries only the explicit permission snapshot selected at creation. Neither belongs in client-side code. A publishable key (`pk_…`) is safe for client-side contexts; it is restricted to payment-method tokenization operations. The full key value is returned exactly once: in the create response and in the rotate response. It is not included in retrieve, list, or revoke responses. Store it securely; it is not retrievable afterwards. Each key is scoped to a mode (`test` or `live`). A test-mode key can only see and mutate test-mode data; a live-mode key operates on production data. The `mode` field on every key reflects which scope applies. Timestamps are Unix epoch seconds. Identifiers are opaque, prefixed strings. Secret key identifiers begin with `sk_`; publishable key identifiers begin with `pk_`. Authentication uses a merchant standard (`sk_…`) or restricted (`rk_…`) secret key as a bearer token. Read endpoints require the `api_keys:read` permission; write endpoints require `api_keys:write`. Create, revoke, and rotate additionally require a secret key; list and retrieve accept any key type with the `api_keys:read` permission. Errors are returned as `{ "error": { "code": "...", "message": "..." } }`. servers: - url: '{baseUrl}/v1' variables: baseUrl: default: https://api.ionicfi.com description: API base URL for your environment. security: - secretKey: [] tags: - name: API Keys description: Create, list, retrieve, revoke, and rotate API keys. paths: /keys/{id}/rotate: parameters: - $ref: '#/components/parameters/APIKeyId' post: tags: - API Keys summary: Rotate an API key description: > Generates a replacement key and transitions the existing key into a grace period. The old key remains usable until its grace period expires, giving you time to deploy the new value before the old one stops working. The new key's full value is returned in this response and never again — store it immediately. The grace period defaults to 24 hours. Set `grace_period_hours` to any value between 1 and 168 (7 days). The grace period cannot extend past the old key's configured expiry time. operationId: api_keys_rotate requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/RotateAPIKeyRequest' responses: '201': description: >- The rotation result, including the new key's full value and the old key's expiry. content: application/json: schema: $ref: '#/components/schemas/RotateAPIKeyResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/APIKeyNotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - api_keys:write components: parameters: APIKeyId: name: id in: path required: true description: >- The API key identifier (`sk_…` for secret keys, `pk_…` for publishable keys). schema: type: string schemas: RotateAPIKeyRequest: type: object description: All fields are optional. properties: grace_period_hours: type: integer description: > How long the old key stays active after rotation, in hours. Must be between 1 and 168 (7 days). Defaults to 24. Cannot extend past the old key's existing expiry time. minimum: 1 maximum: 168 default: 24 RotateAPIKeyResponse: type: object required: - new_key - old_key_expires_at - old_key_id properties: new_key: $ref: '#/components/schemas/APIKeyWithSecret' old_key_id: type: string description: Identifier of the key that was rotated out. old_key_expires_at: type: integer description: >- Unix epoch seconds when the old key stops authenticating requests (end of the grace period). APIKeyWithSecret: type: object description: > Returned when a key is created or rotated. Includes the full authenticatable value (`key`), which is shown exactly once and is not stored by Ionic. Store it immediately. required: - id - key - key_prefix - key_type - mode - owner_id - owner_type - permissions properties: id: type: string description: >- Unique resource identifier. `sk_…` for secret keys; `pk_…` for publishable keys. key: type: string description: >- The full authenticatable token used as the `Authorization: Bearer` value. Present only in create and rotate responses — not included in any other response. key_prefix: type: string description: >- First 19 characters of the full key. Use this to identify the key after the secret is no longer available. key_type: type: string enum: - secret - publishable description: '`secret` for server-side keys; `publishable` for client-side keys.' mode: type: string enum: - test - live description: Environment scope this key operates in. access_profile: type: string enum: - standard - restricted description: | Authorization policy for secret keys. Omitted for publishable keys and for temporarily unclassified legacy rows during rollout. name: type: string nullable: true description: Display name assigned at creation, if set. description: type: string nullable: true description: Notes, if set. owner_type: type: string enum: - merchant - platform description: Whether this key belongs to a merchant or a platform. owner_id: type: string description: Identifier of the owning merchant or platform. permissions: type: array items: type: string description: Permission scopes granted to this key. expires_at: type: integer nullable: true description: >- Unix epoch seconds when the key expires. Null if the key does not expire. Error: type: object properties: error: type: object properties: code: type: string description: A stable, machine-readable error code. message: type: string responses: BadRequest: description: The request was malformed or failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_REQUEST message: mode must be test or live Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The key lacks the required permission. content: application/json: schema: $ref: '#/components/schemas/Error' APIKeyNotFound: description: No key with that identifier is visible to this request. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: API_KEY_NOT_FOUND message: API key not found RateLimited: description: Too many requests. Honour the `Retry-After` header before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' InternalError: description: | The API could not return a successful response. For a mutating request, retrieve the resource before retrying because the operation may have completed. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: secretKey: type: http scheme: bearer description: >- A merchant standard (`sk_…`) or restricted (`rk_…`) secret key sent as `Authorization: Bearer `. ````