Miracle Docs
Api keys

List API keys

Returns a paginated list of API keys visible to the caller, always in the caller's mode. Filters: status, merchantId, createdBy, livemode (a different mode yields an empty page). Uses cursor-based pagination — pass cursor from a previous response to fetch the next page. Default page size is 20, maximum 100. Raw secrets are never included.

GET
/v1/api-keys

Authorization

bearer
AuthorizationBearer <token>

In: header

Query Parameters

status?string

Filter by lifecycle status.

Value in"active" | "revoked" | "expired"
livemode?string

Filter by environment. The list always reads the caller's mode; a different value returns an empty page.

Value in"true" | "false"
merchantId?string

Filter by the merchant that owns the key.

Formatuuid
createdBy?string

Filter by the user or API key that issued the key.

Formatuuid
cursor?string

Pagination cursor returned from a previous list response.

Formatuuid
limit?integer

Page size. Default 20, max 100.

Default20
Range1 <= value <= 100
sortOrder?string

Sort by createdAt. Defaults to descending (newest first).

Value in"asc" | "desc"

Response Body

application/json

curl -X GET "https://<api-host>/v1/api-keys"
{
  "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"
    }
  ],
  "pagination": {
    "nextCursor": "string",
    "prevCursor": "string",
    "hasMore": true,
    "totalCount": 0
  }
}

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`.

Get API key by ID

Returns details for a single API key. The raw secret is never returned — only the public key prefix and metadata.

On this page

AuthorizationResponse Body