# API keys

Organization · PassBook API reference. Authenticate with `Authorization: Bearer $PASSBOOK_KEY`.

## The calling API key: id, name, scopes, organization, mode and use {#retrieveCurrent}

`GET /api/v1/api-keys/me`

The key this request used: its scopes, organization and mode. Use it to check a key works.

SDK name: `pb.apiKeys.retrieveCurrent`.

Returns `200`, a `ApiKeyCurrent`.

| Code | Status | Fix |
| --- | --- | --- |
| `API_KEY_CHILD_CANNOT_MINT` |  | Create the key with the original parent key or from a signed-in session. |
| `API_KEY_CHILD_WIDER` |  | Request only scopes the parent key already holds, or create the key with a broader parent. |
| `API_KEY_MODE_MISMATCH` |  | Call the rotate endpoint with a key in the same mode as the key you rotate. |
| `API_KEY_NOT_FOUND` |  | Look up the id with GET /api/v1/api-keys, using a key of the same mode. |
| `API_KEY_NOT_ROTATABLE` |  | Create a new key with POST /api/v1/api-keys instead of rotating this one. |
| `API_KEY_PARENT_RETIRING` |  | Create the key with a key that is not retiring. |
| `API_KEY_REQUIRED` |  | Call it with Authorization: Bearer $PASSBOOK_KEY. |
| `API_KEY_RESTRICTED_ROUTE` |  | Call this route with a key that has no template restriction. |
| `API_KEY_RESTRICTION_UNSUPPORTED` |  | Set templates and styles only on organization keys that hold pass, holder, template or NFC scopes. |
| `API_KEY_RETIRE_SET` |  | Leave the key as it is, or create a replacement with POST /api/v1/api-keys. |
| `API_KEY_SCAN_ORG_REQUIRED` |  | Create keys with scan scopes under an organization, not the platform. |
| `API_KEY_SCOPE_EXCEEDS_CREATOR` |  | Request only scopes your own key or role holds. |
| `API_KEY_TERMINALS_REQUIRED` |  | Set terminals to at least one terminal. |
| `API_KEY_TERMINALS_UNUSED` |  | Remove terminals, or add the scans:write scope. |
| `EXPIRY_PAST` |  | Send a future time in milliseconds. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |

```sh
curl -X GET "https://passbook.mobile/api/v1/api-keys/me" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-000000000201",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "name": "Order system",
  "prefix": "wlt_k3v9",
  "scopes": [
    "passes:read",
    "passes:write"
  ],
  "mode": "test",
  "createdAt": 1764000000000,
  "lastUsedAt": 1764000060000,
  "expiresAt": null
}
```

## Replace the calling key: the new secret works at once, the old one after the overlap {#rotateCurrent}

`POST /api/v1/api-keys/me/rotate`

Replace the key this request used. The new secret works at once and is shown once; the old key keeps working for `overlapHours`, then stops. Send an `Idempotency-Key` to retry safely.

Scopes: `api-keys:write`. SDK name: `pb.apiKeys.rotateCurrent`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `overlapHours` | body | integer · ≥ 0 · ≤ 168 |  |  |

Returns `201`, a `ApiKeyRotation`.

| Code | Status | Fix |
| --- | --- | --- |
| `API_KEY_CHILD_CANNOT_MINT` |  | Create the key with the original parent key or from a signed-in session. |
| `API_KEY_CHILD_WIDER` |  | Request only scopes the parent key already holds, or create the key with a broader parent. |
| `API_KEY_MODE_MISMATCH` |  | Call the rotate endpoint with a key in the same mode as the key you rotate. |
| `API_KEY_NOT_FOUND` |  | Look up the id with GET /api/v1/api-keys, using a key of the same mode. |
| `API_KEY_NOT_ROTATABLE` |  | Create a new key with POST /api/v1/api-keys instead of rotating this one. |
| `API_KEY_PARENT_RETIRING` |  | Create the key with a key that is not retiring. |
| `API_KEY_REQUIRED` |  | Call it with Authorization: Bearer $PASSBOOK_KEY. |
| `API_KEY_RESTRICTED_ROUTE` |  | Call this route with a key that has no template restriction. |
| `API_KEY_RESTRICTION_UNSUPPORTED` |  | Set templates and styles only on organization keys that hold pass, holder, template or NFC scopes. |
| `API_KEY_RETIRE_SET` |  | Leave the key as it is, or create a replacement with POST /api/v1/api-keys. |
| `API_KEY_SCAN_ORG_REQUIRED` |  | Create keys with scan scopes under an organization, not the platform. |
| `API_KEY_SCOPE_EXCEEDS_CREATOR` |  | Request only scopes your own key or role holds. |
| `API_KEY_TERMINALS_REQUIRED` |  | Set terminals to at least one terminal. |
| `API_KEY_TERMINALS_UNUSED` |  | Remove terminals, or add the scans:write scope. |
| `EXPIRY_PAST` |  | Send a future time in milliseconds. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/api-keys/me/rotate" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "overlapHours": 24
}'
```

Response example:

```json
{
  "key": {
    "id": "0193a1b2-7c00-7000-8000-000000000202",
    "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
    "name": "Order system",
    "prefix": "m4q2",
    "secretPrefix": "pb_live_m4q2",
    "scopes": [
      "passes:read",
      "passes:write"
    ],
    "mode": "test",
    "createdBy": "0193a1b2-7c00-7000-8000-000000000101",
    "createdByName": "Ana Reyes",
    "createdAt": 1764003600000,
    "lastUsedAt": null,
    "expiresAt": null,
    "revokedAt": null,
    "kind": "service",
    "roles": [],
    "retireAt": null,
    "ipAllow": [],
    "templateIds": [],
    "passStyles": [],
    "rateTier": null,
    "parentKeyId": null,
    "rotatedFrom": "0193a1b2-7c00-7000-8000-000000000201",
    "secret": "pb_live_m4q2_Zk3x9Qe7LwT1uV5bN8cR2dFh"
  },
  "previous": {
    "id": "0193a1b2-7c00-7000-8000-000000000201",
    "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
    "name": "Order system",
    "prefix": "k3v9",
    "secretPrefix": "pb_live_k3v9",
    "scopes": [
      "passes:read",
      "passes:write"
    ],
    "mode": "test",
    "createdBy": "0193a1b2-7c00-7000-8000-000000000101",
    "createdByName": "Ana Reyes",
    "createdAt": 1764000000000,
    "lastUsedAt": 1764000060000,
    "expiresAt": null,
    "revokedAt": null,
    "kind": "service",
    "roles": [],
    "retireAt": 1764090000000,
    "ipAllow": [],
    "templateIds": [],
    "passStyles": [],
    "rateTier": null,
    "parentKeyId": null,
    "rotatedFrom": null
  }
}
```

## Replace a key: the new secret works at once, the old one retires after the overlap {#rotate}

`POST /api/v1/api-keys/{id}/rotate`

Replace a key. The new secret works at once and is shown once; the old key keeps working for `overlapHours`, then stops. Send an `Idempotency-Key` to retry safely.

Scopes: `api-keys:write`. SDK name: `pb.apiKeys.rotate`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `orgId` | body | string \| null · max 64 | yes |  |
| `overlapHours` | body | integer · ≥ 0 · ≤ 168 |  |  |

Returns `201`, a `ApiKeyRotation`.

| Code | Status | Fix |
| --- | --- | --- |
| `API_KEY_CHILD_CANNOT_MINT` |  | Create the key with the original parent key or from a signed-in session. |
| `API_KEY_CHILD_WIDER` |  | Request only scopes the parent key already holds, or create the key with a broader parent. |
| `API_KEY_MODE_MISMATCH` |  | Call the rotate endpoint with a key in the same mode as the key you rotate. |
| `API_KEY_NOT_FOUND` |  | Look up the id with GET /api/v1/api-keys, using a key of the same mode. |
| `API_KEY_NOT_ROTATABLE` |  | Create a new key with POST /api/v1/api-keys instead of rotating this one. |
| `API_KEY_PARENT_RETIRING` |  | Create the key with a key that is not retiring. |
| `API_KEY_REQUIRED` |  | Call it with Authorization: Bearer $PASSBOOK_KEY. |
| `API_KEY_RESTRICTED_ROUTE` |  | Call this route with a key that has no template restriction. |
| `API_KEY_RESTRICTION_UNSUPPORTED` |  | Set templates and styles only on organization keys that hold pass, holder, template or NFC scopes. |
| `API_KEY_RETIRE_SET` |  | Leave the key as it is, or create a replacement with POST /api/v1/api-keys. |
| `API_KEY_SCAN_ORG_REQUIRED` |  | Create keys with scan scopes under an organization, not the platform. |
| `API_KEY_SCOPE_EXCEEDS_CREATOR` |  | Request only scopes your own key or role holds. |
| `API_KEY_TERMINALS_REQUIRED` |  | Set terminals to at least one terminal. |
| `API_KEY_TERMINALS_UNUSED` |  | Remove terminals, or add the scans:write scope. |
| `EXPIRY_PAST` |  | Send a future time in milliseconds. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/api-keys/0193a1b2-7c00-7000-8000-0000000000e1/rotate" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "overlapHours": 24
}'
```

Response example:

```json
{
  "key": {
    "id": "0193a1b2-7c00-7000-8000-000000000202",
    "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
    "name": "Order system",
    "prefix": "m4q2",
    "secretPrefix": "pb_live_m4q2",
    "scopes": [
      "passes:read",
      "passes:write"
    ],
    "mode": "test",
    "createdBy": "0193a1b2-7c00-7000-8000-000000000101",
    "createdByName": "Ana Reyes",
    "createdAt": 1764003600000,
    "lastUsedAt": null,
    "expiresAt": null,
    "revokedAt": null,
    "kind": "service",
    "roles": [],
    "retireAt": null,
    "ipAllow": [],
    "templateIds": [],
    "passStyles": [],
    "rateTier": null,
    "parentKeyId": null,
    "rotatedFrom": "0193a1b2-7c00-7000-8000-000000000201",
    "secret": "pb_live_m4q2_Zk3x9Qe7LwT1uV5bN8cR2dFh"
  },
  "previous": {
    "id": "0193a1b2-7c00-7000-8000-000000000201",
    "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
    "name": "Order system",
    "prefix": "k3v9",
    "secretPrefix": "pb_live_k3v9",
    "scopes": [
      "passes:read",
      "passes:write"
    ],
    "mode": "test",
    "createdBy": "0193a1b2-7c00-7000-8000-000000000101",
    "createdByName": "Ana Reyes",
    "createdAt": 1764000000000,
    "lastUsedAt": 1764000060000,
    "expiresAt": null,
    "revokedAt": null,
    "kind": "service",
    "roles": [],
    "retireAt": 1764090000000,
    "ipAllow": [],
    "templateIds": [],
    "passStyles": [],
    "rateTier": null,
    "parentKeyId": null,
    "rotatedFrom": null
  }
}
```

## A key with its parent, successor, children count and last use {#retrieve}

`GET /api/v1/api-keys/{id}`

One key with its parent, the key that replaced it, how many child keys it has, and where it was last used from. Never the secret.

Scopes: `api-keys:write`. SDK name: `pb.apiKeys.retrieve`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`, a `ApiKeyDetail`.

| Code | Status | Fix |
| --- | --- | --- |
| `API_KEY_CHILD_CANNOT_MINT` |  | Create the key with the original parent key or from a signed-in session. |
| `API_KEY_CHILD_WIDER` |  | Request only scopes the parent key already holds, or create the key with a broader parent. |
| `API_KEY_MODE_MISMATCH` |  | Call the rotate endpoint with a key in the same mode as the key you rotate. |
| `API_KEY_NOT_FOUND` |  | Look up the id with GET /api/v1/api-keys, using a key of the same mode. |
| `API_KEY_NOT_ROTATABLE` |  | Create a new key with POST /api/v1/api-keys instead of rotating this one. |
| `API_KEY_PARENT_RETIRING` |  | Create the key with a key that is not retiring. |
| `API_KEY_REQUIRED` |  | Call it with Authorization: Bearer $PASSBOOK_KEY. |
| `API_KEY_RESTRICTED_ROUTE` |  | Call this route with a key that has no template restriction. |
| `API_KEY_RESTRICTION_UNSUPPORTED` |  | Set templates and styles only on organization keys that hold pass, holder, template or NFC scopes. |
| `API_KEY_RETIRE_SET` |  | Leave the key as it is, or create a replacement with POST /api/v1/api-keys. |
| `API_KEY_SCAN_ORG_REQUIRED` |  | Create keys with scan scopes under an organization, not the platform. |
| `API_KEY_SCOPE_EXCEEDS_CREATOR` |  | Request only scopes your own key or role holds. |
| `API_KEY_TERMINALS_REQUIRED` |  | Set terminals to at least one terminal. |
| `API_KEY_TERMINALS_UNUSED` |  | Remove terminals, or add the scans:write scope. |
| `EXPIRY_PAST` |  | Send a future time in milliseconds. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X GET "https://passbook.mobile/api/v1/api-keys/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-000000000201",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "name": "Order system",
  "prefix": "k3v9",
  "secretPrefix": "pb_live_k3v9",
  "scopes": [
    "passes:read",
    "passes:write"
  ],
  "mode": "test",
  "createdBy": "0193a1b2-7c00-7000-8000-000000000101",
  "createdByName": "Ana Reyes",
  "createdAt": 1764000000000,
  "lastUsedAt": 1764000060000,
  "expiresAt": null,
  "revokedAt": null,
  "kind": "service",
  "roles": [],
  "retireAt": null,
  "ipAllow": [],
  "templateIds": [],
  "passStyles": [],
  "rateTier": null,
  "parentKeyId": null,
  "rotatedFrom": null,
  "lastIpPrefix": "203.0.113.0/24",
  "parent": null,
  "replacedBy": null,
  "childCount": 0
}
```

## Revoke a key for an authorized organization, or a platform-wide key with orgId=null {#revoke}

`DELETE /api/v1/api-keys/{id}`

Scopes: `api-keys:write`. SDK name: `pb.apiKeys.revoke`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `API_KEY_CHILD_CANNOT_MINT` |  | Create the key with the original parent key or from a signed-in session. |
| `API_KEY_CHILD_WIDER` |  | Request only scopes the parent key already holds, or create the key with a broader parent. |
| `API_KEY_MODE_MISMATCH` |  | Call the rotate endpoint with a key in the same mode as the key you rotate. |
| `API_KEY_NOT_FOUND` |  | Look up the id with GET /api/v1/api-keys, using a key of the same mode. |
| `API_KEY_NOT_ROTATABLE` |  | Create a new key with POST /api/v1/api-keys instead of rotating this one. |
| `API_KEY_PARENT_RETIRING` |  | Create the key with a key that is not retiring. |
| `API_KEY_REQUIRED` |  | Call it with Authorization: Bearer $PASSBOOK_KEY. |
| `API_KEY_RESTRICTED_ROUTE` |  | Call this route with a key that has no template restriction. |
| `API_KEY_RESTRICTION_UNSUPPORTED` |  | Set templates and styles only on organization keys that hold pass, holder, template or NFC scopes. |
| `API_KEY_RETIRE_SET` |  | Leave the key as it is, or create a replacement with POST /api/v1/api-keys. |
| `API_KEY_SCAN_ORG_REQUIRED` |  | Create keys with scan scopes under an organization, not the platform. |
| `API_KEY_SCOPE_EXCEEDS_CREATOR` |  | Request only scopes your own key or role holds. |
| `API_KEY_TERMINALS_REQUIRED` |  | Set terminals to at least one terminal. |
| `API_KEY_TERMINALS_UNUSED` |  | Remove terminals, or add the scans:write scope. |
| `EXPIRY_PAST` |  | Send a future time in milliseconds. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X DELETE "https://passbook.mobile/api/v1/api-keys/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## List keys for an authorized organization, or platform-wide keys with orgId=null {#list}

`GET /api/v1/api-keys`

Scopes: `api-keys:write`. SDK name: `pb.apiKeys.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string · max 512 |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |
| `state` | query | "live" \| "revoked" |  |  |
| `parentKeyId` | query | string · max 64 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `API_KEY_CHILD_CANNOT_MINT` |  | Create the key with the original parent key or from a signed-in session. |
| `API_KEY_CHILD_WIDER` |  | Request only scopes the parent key already holds, or create the key with a broader parent. |
| `API_KEY_MODE_MISMATCH` |  | Call the rotate endpoint with a key in the same mode as the key you rotate. |
| `API_KEY_NOT_FOUND` |  | Look up the id with GET /api/v1/api-keys, using a key of the same mode. |
| `API_KEY_NOT_ROTATABLE` |  | Create a new key with POST /api/v1/api-keys instead of rotating this one. |
| `API_KEY_PARENT_RETIRING` |  | Create the key with a key that is not retiring. |
| `API_KEY_REQUIRED` |  | Call it with Authorization: Bearer $PASSBOOK_KEY. |
| `API_KEY_RESTRICTED_ROUTE` |  | Call this route with a key that has no template restriction. |
| `API_KEY_RESTRICTION_UNSUPPORTED` |  | Set templates and styles only on organization keys that hold pass, holder, template or NFC scopes. |
| `API_KEY_RETIRE_SET` |  | Leave the key as it is, or create a replacement with POST /api/v1/api-keys. |
| `API_KEY_SCAN_ORG_REQUIRED` |  | Create keys with scan scopes under an organization, not the platform. |
| `API_KEY_SCOPE_EXCEEDS_CREATOR` |  | Request only scopes your own key or role holds. |
| `API_KEY_TERMINALS_REQUIRED` |  | Set terminals to at least one terminal. |
| `API_KEY_TERMINALS_UNUSED` |  | Remove terminals, or add the scans:write scope. |
| `EXPIRY_PAST` |  | Send a future time in milliseconds. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X GET "https://passbook.mobile/api/v1/api-keys" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Create an organization or platform API key {#create}

`POST /api/v1/api-keys`

Scopes: `api-keys:write`. SDK name: `pb.apiKeys.create`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | body | string \| null · max 64 | yes |  |
| `name` | body | string · max 120 | yes |  |
| `kind` | body | "service" \| "personal" \| "platform" |  |  |
| `scopes` | body | "passes:read" \| "passes:write" \| "holders:write" \| "templates:read" \| "messages:write" \| "scans:read" \| "scans:write" \| "connections:read" \| "connections:write" \| "webhooks:manage" \| "brand:manage" \| "scanning:write" \| "api-keys:write"[] |  |  |
| `roles` | body | "org_admin" \| "integration_admin" \| "template_author" \| "template_reviewer" \| "template_publisher" \| "pass_operator" \| "read_only"[] |  |  |
| `ipAllow` | body | string · max 60[] |  |  |
| `templateIds` | body | string · max 64[] |  |  |
| `passStyles` | body | "generic" \| "posterGeneric" \| "storeCard" \| "coupon" \| "eventTicket" \| "boardingPass"[] |  |  |
| `terminalIds` | body | string · max 64[] |  |  |
| `mode` | body | "live" \| "test" |  |  |
| `expiresAt` | body | integer \| null · ≥ 0 |  |  |

Returns `201`, a `ApiKeyMinted`.

| Code | Status | Fix |
| --- | --- | --- |
| `API_KEY_CHILD_CANNOT_MINT` |  | Create the key with the original parent key or from a signed-in session. |
| `API_KEY_CHILD_WIDER` |  | Request only scopes the parent key already holds, or create the key with a broader parent. |
| `API_KEY_MODE_MISMATCH` |  | Call the rotate endpoint with a key in the same mode as the key you rotate. |
| `API_KEY_NOT_FOUND` |  | Look up the id with GET /api/v1/api-keys, using a key of the same mode. |
| `API_KEY_NOT_ROTATABLE` |  | Create a new key with POST /api/v1/api-keys instead of rotating this one. |
| `API_KEY_PARENT_RETIRING` |  | Create the key with a key that is not retiring. |
| `API_KEY_REQUIRED` |  | Call it with Authorization: Bearer $PASSBOOK_KEY. |
| `API_KEY_RESTRICTED_ROUTE` |  | Call this route with a key that has no template restriction. |
| `API_KEY_RESTRICTION_UNSUPPORTED` |  | Set templates and styles only on organization keys that hold pass, holder, template or NFC scopes. |
| `API_KEY_RETIRE_SET` |  | Leave the key as it is, or create a replacement with POST /api/v1/api-keys. |
| `API_KEY_SCAN_ORG_REQUIRED` |  | Create keys with scan scopes under an organization, not the platform. |
| `API_KEY_SCOPE_EXCEEDS_CREATOR` |  | Request only scopes your own key or role holds. |
| `API_KEY_TERMINALS_REQUIRED` |  | Set terminals to at least one terminal. |
| `API_KEY_TERMINALS_UNUSED` |  | Remove terminals, or add the scans:write scope. |
| `EXPIRY_PAST` |  | Send a future time in milliseconds. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/api-keys" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "name": "CI",
  "scopes": [
    "passes:read"
  ],
  "mode": "test"
}'
```

## Retire a key at a later instant: it stops working then {#retire}

`POST /api/v1/api-keys/{id}/retire`

Set the instant a key stops working, earlier than its expiry. Set once; the key works until then.

Scopes: `api-keys:write`. SDK name: `pb.apiKeys.retire`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `orgId` | body | string \| null · max 64 | yes |  |
| `retireAt` | body | integer · ≥ 0 | yes |  |

Returns `200`, a `ApiKeyRetired`.

| Code | Status | Fix |
| --- | --- | --- |
| `API_KEY_CHILD_CANNOT_MINT` |  | Create the key with the original parent key or from a signed-in session. |
| `API_KEY_CHILD_WIDER` |  | Request only scopes the parent key already holds, or create the key with a broader parent. |
| `API_KEY_MODE_MISMATCH` |  | Call the rotate endpoint with a key in the same mode as the key you rotate. |
| `API_KEY_NOT_FOUND` |  | Look up the id with GET /api/v1/api-keys, using a key of the same mode. |
| `API_KEY_NOT_ROTATABLE` |  | Create a new key with POST /api/v1/api-keys instead of rotating this one. |
| `API_KEY_PARENT_RETIRING` |  | Create the key with a key that is not retiring. |
| `API_KEY_REQUIRED` |  | Call it with Authorization: Bearer $PASSBOOK_KEY. |
| `API_KEY_RESTRICTED_ROUTE` |  | Call this route with a key that has no template restriction. |
| `API_KEY_RESTRICTION_UNSUPPORTED` |  | Set templates and styles only on organization keys that hold pass, holder, template or NFC scopes. |
| `API_KEY_RETIRE_SET` |  | Leave the key as it is, or create a replacement with POST /api/v1/api-keys. |
| `API_KEY_SCAN_ORG_REQUIRED` |  | Create keys with scan scopes under an organization, not the platform. |
| `API_KEY_SCOPE_EXCEEDS_CREATOR` |  | Request only scopes your own key or role holds. |
| `API_KEY_TERMINALS_REQUIRED` |  | Set terminals to at least one terminal. |
| `API_KEY_TERMINALS_UNUSED` |  | Remove terminals, or add the scans:write scope. |
| `EXPIRY_PAST` |  | Send a future time in milliseconds. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/api-keys/0193a1b2-7c00-7000-8000-0000000000e1/retire" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "retireAt": 1764090000000
}'
```

Response example:

```json
{
  "ok": true
}
```

## What a key did lately: calls by action and the latest calls, without bodies or secrets {#activity-list}

`GET /api/v1/api-keys/{id}/activity`

What a key did lately: calls by action over the last 30 days and the latest calls. No request bodies, no secrets.

Scopes: `api-keys:write`. SDK name: `pb.apiKeys.activity.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `limit` | query | integer · ≥ 1 · ≤ 100 |  |  |

Returns `200`, a `ApiKeyActivity`.

| Code | Status | Fix |
| --- | --- | --- |
| `API_KEY_CHILD_CANNOT_MINT` |  | Create the key with the original parent key or from a signed-in session. |
| `API_KEY_CHILD_WIDER` |  | Request only scopes the parent key already holds, or create the key with a broader parent. |
| `API_KEY_MODE_MISMATCH` |  | Call the rotate endpoint with a key in the same mode as the key you rotate. |
| `API_KEY_NOT_FOUND` |  | Look up the id with GET /api/v1/api-keys, using a key of the same mode. |
| `API_KEY_NOT_ROTATABLE` |  | Create a new key with POST /api/v1/api-keys instead of rotating this one. |
| `API_KEY_PARENT_RETIRING` |  | Create the key with a key that is not retiring. |
| `API_KEY_REQUIRED` |  | Call it with Authorization: Bearer $PASSBOOK_KEY. |
| `API_KEY_RESTRICTED_ROUTE` |  | Call this route with a key that has no template restriction. |
| `API_KEY_RESTRICTION_UNSUPPORTED` |  | Set templates and styles only on organization keys that hold pass, holder, template or NFC scopes. |
| `API_KEY_RETIRE_SET` |  | Leave the key as it is, or create a replacement with POST /api/v1/api-keys. |
| `API_KEY_SCAN_ORG_REQUIRED` |  | Create keys with scan scopes under an organization, not the platform. |
| `API_KEY_SCOPE_EXCEEDS_CREATOR` |  | Request only scopes your own key or role holds. |
| `API_KEY_TERMINALS_REQUIRED` |  | Set terminals to at least one terminal. |
| `API_KEY_TERMINALS_UNUSED` |  | Remove terminals, or add the scans:write scope. |
| `EXPIRY_PAST` |  | Send a future time in milliseconds. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X GET "https://passbook.mobile/api/v1/api-keys/0193a1b2-7c00-7000-8000-0000000000e1/activity" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "lastUsedAt": 1764000060000,
  "lastIpPrefix": "203.0.113.0/24",
  "summary": {
    "since": 1761408000000,
    "calls": 412,
    "denied": 3,
    "actions": [
      {
        "action": "pass.create",
        "count": 390,
        "lastAt": 1764000060000
      }
    ]
  },
  "recent": [
    {
      "id": 9120,
      "at": 1764000060000,
      "action": "pass.create",
      "outcome": "allowed",
      "targetType": "pass",
      "targetId": "0193a1b2-7c00-7000-8000-0000000000c1",
      "ipPrefix": "203.0.113.0/24",
      "code": null
    }
  ]
}
```
