> ## 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. # Create a secret API key > Creates a standard (`sk_…`) or restricted (`rk_…`) secret key owned by the authenticated principal. Omit both `access_profile` and `permissions` for standard access. Supplying a non-empty permission list without a profile creates a restricted key for backward compatibility. The full key value is returned in this response and never again — store it immediately. Secret keys are for server-side use only and must never be exposed to clients or embedded in frontend code. ## OpenAPI ````yaml /openapi/api_keys.yaml post /keys/secret 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/secret: post: tags: - API Keys summary: Create a secret API key description: > Creates a standard (`sk_…`) or restricted (`rk_…`) secret key owned by the authenticated principal. Omit both `access_profile` and `permissions` for standard access. Supplying a non-empty permission list without a profile creates a restricted key for backward compatibility. The full key value is returned in this response and never again — store it immediately. Secret keys are for server-side use only and must never be exposed to clients or embedded in frontend code. operationId: api_keys_create_secret requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAPIKeyRequest' responses: '201': description: The created secret key, including its full value. content: application/json: schema: $ref: '#/components/schemas/APIKeyWithSecret' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' security: - secretKey: - api_keys:write components: schemas: CreateAPIKeyRequest: type: object required: - mode properties: mode: type: string enum: - test - live description: Environment scope. `test` for sandbox; `live` for production. name: type: string nullable: true description: Optional display name for the key. description: type: string nullable: true description: Optional notes about the key's intended use. access_profile: type: string enum: - standard - restricted description: | Authorization policy for a secret key. `standard` follows Ionic's current explicitly registered data-plane policy; when explicitly selected, the `permissions` field must be omitted (even an empty array is rejected). `restricted` is a deny-by-default snapshot and requires at least one explicit permission. Omit with no permissions to create a standard key; omit with explicit permissions to infer restricted access. Publishable keys do not support this field. permissions: type: array items: type: string description: > Permission scopes granted to the key. Values follow the `resource:action` pattern, for example `payments:write` or `api_keys:read`. A non-empty permission list creates restricted access unless `access_profile` is explicitly set, in which case it must be `restricted`. Restricted access requires at least one permission. An explicitly selected standard profile rejects the field, including an empty array. Merchant account and lifecycle permissions are not grantable API-key scopes; historical `merchants:read` and `merchants:write` values are inert. expires_at: type: string description: >- RFC 3339 timestamp when the key expires. Must be in the future. Omit for a non-expiring key. example: '2027-06-01T00:00:00Z' 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' 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 `. ````