Skip to main content
POST
Error

Authorizations

​
Authorization
string
header
required

A merchant standard (sk_…) or restricted (rk_…) secret key sent as Authorization: Bearer <key>.

Body

application/json
​
mode
enum<string>
required

Environment scope. test for sandbox; live for production.

Available options:
test,
live
​
name
string | null

Optional display name for the key.

​
description
string | null

Optional notes about the key's intended use.

​
access_profile
enum<string>

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.

Available options:
standard,
restricted
​
permissions
string[]

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
string

RFC 3339 timestamp when the key expires. Must be in the future. Omit for a non-expiring key.

Example:

"2027-06-01T00:00:00Z"

Response

The created publishable key, including its full value.

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.

​
id
string
required

Unique resource identifier. sk_… for secret keys; pk_… for publishable keys.

​
key
string
required

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
string
required

First 19 characters of the full key. Use this to identify the key after the secret is no longer available.

​
key_type
enum<string>
required

secret for server-side keys; publishable for client-side keys.

Available options:
secret,
publishable
​
mode
enum<string>
required

Environment scope this key operates in.

Available options:
test,
live
​
owner_type
enum<string>
required

Whether this key belongs to a merchant or a platform.

Available options:
merchant,
platform
​
owner_id
string
required

Identifier of the owning merchant or platform.

​
permissions
string[]
required

Permission scopes granted to this key.

​
access_profile
enum<string>

Authorization policy for secret keys. Omitted for publishable keys and for temporarily unclassified legacy rows during rollout.

Available options:
standard,
restricted
​
name
string | null

Display name assigned at creation, if set.

​
description
string | null

Notes, if set.

​
expires_at
integer | null

Unix epoch seconds when the key expires. Null if the key does not expire.