Create a new API key pair

Issues a new API key pair (public + secret). The plain-text secret is returned ONCE in the response — store it securely. Subsequent reads return only the public portion. Pass ownerType: "merchant" with merchantId to bind the key to a single merchant, or ownerType: "tenant" for a tenant-wide key. Use livemode: false to create a sandbox key (sk_test_*). A secret-key caller issues keys only in its own mode. Repeating the request with the same Idempotency-Key answers 409 API_KEY_ALREADY_ISSUED with the issued key id in instance.

Authorization

bearer

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key*string

Unique per issuing request, 1-128 characters. A replay never issues a second key and never reveals the secret again.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Human-readable name for the new API key.

Length1 <= length <= 256

ownerType*string

Owner scope. "merchant" issues a key bound to a single merchant; "tenant" issues a tenant-wide key.

Value in"merchant" | "tenant"

merchantId?string

Merchant ID. Required when ownerType is "merchant".

Formatuuid

keyType?string

Key variant. "public" issues a pk_, "secret" issues an sk_, "webhook_secret" issues a whsec_*.

Default"secret"

Value in"public" | "secret" | "webhook_secret"

inboundFormat?string

Immutable inbound-compat format the key authenticates for. Foreign formats (e.g. adyen_hosted) are dispatched to an input adapter emulating that API. Operator/owner-provisioned only.

Default"miracle_native"

Value in"miracle_native" | "stripe_compat" | "adyen_hosted" | "checkoutcom_hpp"

livemode*boolean

true creates a live key (sk_live_); false creates a test key (sk_test_).

permissions*array<string>

Explicit permission codes. An empty array creates a key with no permissions.

ipAllowlist?array<>

CIDR expressions that restrict where the key may be used from.

Default[]

Itemsitems <= 50

expiresAt?|

Expiry timestamp (ISO 8601). Omit or pass null for a key that never expires.

Formatdate-time

Response Body

`application/json`

curl -X POST "https://<api-host>/v1/api-keys" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "ownerType": "merchant",    "livemode": true,    "permissions": [      "string"    ]  }'

{
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0",
    "livemode": true,
    "owner": {
      "type": "merchant",
      "merchantId": "c3073b9d-edd0-49f2-a28d-b7ded8ff9a8b",
      "tenantId": "f97df110-f4de-492e-8849-4a6af68026b0"
    },
    "environment": "test",
    "keyType": "public",
    "inboundFormat": "miracle_native",
    "publicKey": "string",
    "name": "string",
    "status": "active",
    "permissions": [
      "string"
    ],
    "ipAllowlist": [
      "string"
    ],
    "expiresAt": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "deletedAt": null,
    "revokedAt": "string",
    "rotatedFromKeyId": "398ea6c9-3802-4188-a0cb-054a865227fd",
    "createdBy": "25a02396-1048-48f9-bf93-102d2fb7895e",
    "createdByType": "user",
    "secretKey": "string"
  }
}

Empty