API keys
9 operations. Send Authorization: Bearer $PASSBOOK_KEY. Markdown
/api/v1/api-keys/meThe key this request used: its scopes, organization and mode. Use it to check a key works.
Returns
200 ApiKeyCurrent
Errors
| 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. |
Replace the calling key: the new secret works at once, the old one after the overlap
New in 2026-11-20/api/v1/api-keys/me/rotateReplace 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.
Body
Returns
201 ApiKeyRotation
Errors
| 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. |
/api/v1/api-keys/{id}/rotateReplace 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.
Path
Body
Returns
201 ApiKeyRotation
Errors
| 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. |
/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.
Path
Returns
200 ApiKeyDetail
Errors
| 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. |
/api/v1/api-keys/{id}Path
Returns
200
Errors
| 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. |
/api/v1/api-keysQuery
Returns
200
Errors
| 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. |
/api/v1/api-keysBody
Returns
201 ApiKeyMinted
Errors
| 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. |
/api/v1/api-keys/{id}/retireSet the instant a key stops working, earlier than its expiry. Set once; the key works until then.
Path
Body
Returns
200 ApiKeyRetired
Errors
| 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. |
Activity
What a key did lately: calls by action and the latest calls, without bodies or secrets
New in 2026-11-20/api/v1/api-keys/{id}/activityWhat a key did lately: calls by action over the last 30 days and the latest calls. No request bodies, no secrets.
Path
Query
Returns
200 ApiKeyActivity
Errors
| 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. |