ReferenceOrganization

API keys

9 operations. Send Authorization: Bearer $PASSBOOK_KEY. Markdown

GET/api/v1/api-keys/me

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

SDK pb.apiKeys.retrieveCurrent

Returns

200 ApiKeyCurrent

Errors

CodeStatusFix
API_KEY_CHILD_CANNOT_MINTCreate the key with the original parent key or from a signed-in session.
API_KEY_CHILD_WIDERRequest only scopes the parent key already holds, or create the key with a broader parent.
API_KEY_MODE_MISMATCHCall the rotate endpoint with a key in the same mode as the key you rotate.
API_KEY_NOT_FOUNDLook up the id with GET /api/v1/api-keys, using a key of the same mode.
API_KEY_NOT_ROTATABLECreate a new key with POST /api/v1/api-keys instead of rotating this one.
API_KEY_PARENT_RETIRINGCreate the key with a key that is not retiring.
API_KEY_REQUIREDCall it with Authorization: Bearer $PASSBOOK_KEY.
API_KEY_RESTRICTED_ROUTECall this route with a key that has no template restriction.
API_KEY_RESTRICTION_UNSUPPORTEDSet templates and styles only on organization keys that hold pass, holder, template or NFC scopes.
API_KEY_RETIRE_SETLeave the key as it is, or create a replacement with POST /api/v1/api-keys.
API_KEY_SCAN_ORG_REQUIREDCreate keys with scan scopes under an organization, not the platform.
API_KEY_SCOPE_EXCEEDS_CREATORRequest only scopes your own key or role holds.
API_KEY_TERMINALS_REQUIREDSet terminals to at least one terminal.
API_KEY_TERMINALS_UNUSEDRemove terminals, or add the scans:write scope.
EXPIRY_PASTSend a future time in milliseconds.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
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.

api-keys:writeSDK pb.apiKeys.rotateCurrent

Body

overlapHoursinteger · ≥ 0 · ≤ 168

Returns

201 ApiKeyRotation

Errors

CodeStatusFix
API_KEY_CHILD_CANNOT_MINTCreate the key with the original parent key or from a signed-in session.
API_KEY_CHILD_WIDERRequest only scopes the parent key already holds, or create the key with a broader parent.
API_KEY_MODE_MISMATCHCall the rotate endpoint with a key in the same mode as the key you rotate.
API_KEY_NOT_FOUNDLook up the id with GET /api/v1/api-keys, using a key of the same mode.
API_KEY_NOT_ROTATABLECreate a new key with POST /api/v1/api-keys instead of rotating this one.
API_KEY_PARENT_RETIRINGCreate the key with a key that is not retiring.
API_KEY_REQUIREDCall it with Authorization: Bearer $PASSBOOK_KEY.
API_KEY_RESTRICTED_ROUTECall this route with a key that has no template restriction.
API_KEY_RESTRICTION_UNSUPPORTEDSet templates and styles only on organization keys that hold pass, holder, template or NFC scopes.
API_KEY_RETIRE_SETLeave the key as it is, or create a replacement with POST /api/v1/api-keys.
API_KEY_SCAN_ORG_REQUIREDCreate keys with scan scopes under an organization, not the platform.
API_KEY_SCOPE_EXCEEDS_CREATORRequest only scopes your own key or role holds.
API_KEY_TERMINALS_REQUIREDSet terminals to at least one terminal.
API_KEY_TERMINALS_UNUSEDRemove terminals, or add the scans:write scope.
EXPIRY_PASTSend a future time in milliseconds.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
VALIDATIONFix each field in issues and resend.
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.

api-keys:writeSDK pb.apiKeys.rotate

Path

idstring · max 64Required

Body

orgIdstring | null · max 64Required
overlapHoursinteger · ≥ 0 · ≤ 168

Returns

201 ApiKeyRotation

Errors

CodeStatusFix
API_KEY_CHILD_CANNOT_MINTCreate the key with the original parent key or from a signed-in session.
API_KEY_CHILD_WIDERRequest only scopes the parent key already holds, or create the key with a broader parent.
API_KEY_MODE_MISMATCHCall the rotate endpoint with a key in the same mode as the key you rotate.
API_KEY_NOT_FOUNDLook up the id with GET /api/v1/api-keys, using a key of the same mode.
API_KEY_NOT_ROTATABLECreate a new key with POST /api/v1/api-keys instead of rotating this one.
API_KEY_PARENT_RETIRINGCreate the key with a key that is not retiring.
API_KEY_REQUIREDCall it with Authorization: Bearer $PASSBOOK_KEY.
API_KEY_RESTRICTED_ROUTECall this route with a key that has no template restriction.
API_KEY_RESTRICTION_UNSUPPORTEDSet templates and styles only on organization keys that hold pass, holder, template or NFC scopes.
API_KEY_RETIRE_SETLeave the key as it is, or create a replacement with POST /api/v1/api-keys.
API_KEY_SCAN_ORG_REQUIREDCreate keys with scan scopes under an organization, not the platform.
API_KEY_SCOPE_EXCEEDS_CREATORRequest only scopes your own key or role holds.
API_KEY_TERMINALS_REQUIREDSet terminals to at least one terminal.
API_KEY_TERMINALS_UNUSEDRemove terminals, or add the scans:write scope.
EXPIRY_PASTSend a future time in milliseconds.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
VALIDATIONFix each field in issues and resend.
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.

api-keys:writeSDK pb.apiKeys.retrieve

Path

idstring · max 64Required

Returns

200 ApiKeyDetail

Errors

CodeStatusFix
API_KEY_CHILD_CANNOT_MINTCreate the key with the original parent key or from a signed-in session.
API_KEY_CHILD_WIDERRequest only scopes the parent key already holds, or create the key with a broader parent.
API_KEY_MODE_MISMATCHCall the rotate endpoint with a key in the same mode as the key you rotate.
API_KEY_NOT_FOUNDLook up the id with GET /api/v1/api-keys, using a key of the same mode.
API_KEY_NOT_ROTATABLECreate a new key with POST /api/v1/api-keys instead of rotating this one.
API_KEY_PARENT_RETIRINGCreate the key with a key that is not retiring.
API_KEY_REQUIREDCall it with Authorization: Bearer $PASSBOOK_KEY.
API_KEY_RESTRICTED_ROUTECall this route with a key that has no template restriction.
API_KEY_RESTRICTION_UNSUPPORTEDSet templates and styles only on organization keys that hold pass, holder, template or NFC scopes.
API_KEY_RETIRE_SETLeave the key as it is, or create a replacement with POST /api/v1/api-keys.
API_KEY_SCAN_ORG_REQUIREDCreate keys with scan scopes under an organization, not the platform.
API_KEY_SCOPE_EXCEEDS_CREATORRequest only scopes your own key or role holds.
API_KEY_TERMINALS_REQUIREDSet terminals to at least one terminal.
API_KEY_TERMINALS_UNUSEDRemove terminals, or add the scans:write scope.
EXPIRY_PASTSend a future time in milliseconds.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
VALIDATIONFix each field in issues and resend.
DEL/api/v1/api-keys/{id}
api-keys:writeSDK pb.apiKeys.revoke

Path

idstring · max 64Required

Returns

200

Errors

CodeStatusFix
API_KEY_CHILD_CANNOT_MINTCreate the key with the original parent key or from a signed-in session.
API_KEY_CHILD_WIDERRequest only scopes the parent key already holds, or create the key with a broader parent.
API_KEY_MODE_MISMATCHCall the rotate endpoint with a key in the same mode as the key you rotate.
API_KEY_NOT_FOUNDLook up the id with GET /api/v1/api-keys, using a key of the same mode.
API_KEY_NOT_ROTATABLECreate a new key with POST /api/v1/api-keys instead of rotating this one.
API_KEY_PARENT_RETIRINGCreate the key with a key that is not retiring.
API_KEY_REQUIREDCall it with Authorization: Bearer $PASSBOOK_KEY.
API_KEY_RESTRICTED_ROUTECall this route with a key that has no template restriction.
API_KEY_RESTRICTION_UNSUPPORTEDSet templates and styles only on organization keys that hold pass, holder, template or NFC scopes.
API_KEY_RETIRE_SETLeave the key as it is, or create a replacement with POST /api/v1/api-keys.
API_KEY_SCAN_ORG_REQUIREDCreate keys with scan scopes under an organization, not the platform.
API_KEY_SCOPE_EXCEEDS_CREATORRequest only scopes your own key or role holds.
API_KEY_TERMINALS_REQUIREDSet terminals to at least one terminal.
API_KEY_TERMINALS_UNUSEDRemove terminals, or add the scans:write scope.
EXPIRY_PASTSend a future time in milliseconds.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
VALIDATIONFix each field in issues and resend.
GET/api/v1/api-keys
api-keys:writeSDK pb.apiKeys.list

Query

cursorstring · max 512
limitinteger · ≥ 1 · ≤ 200
state"live" | "revoked"
parentKeyIdstring · max 64

Returns

200

Errors

CodeStatusFix
API_KEY_CHILD_CANNOT_MINTCreate the key with the original parent key or from a signed-in session.
API_KEY_CHILD_WIDERRequest only scopes the parent key already holds, or create the key with a broader parent.
API_KEY_MODE_MISMATCHCall the rotate endpoint with a key in the same mode as the key you rotate.
API_KEY_NOT_FOUNDLook up the id with GET /api/v1/api-keys, using a key of the same mode.
API_KEY_NOT_ROTATABLECreate a new key with POST /api/v1/api-keys instead of rotating this one.
API_KEY_PARENT_RETIRINGCreate the key with a key that is not retiring.
API_KEY_REQUIREDCall it with Authorization: Bearer $PASSBOOK_KEY.
API_KEY_RESTRICTED_ROUTECall this route with a key that has no template restriction.
API_KEY_RESTRICTION_UNSUPPORTEDSet templates and styles only on organization keys that hold pass, holder, template or NFC scopes.
API_KEY_RETIRE_SETLeave the key as it is, or create a replacement with POST /api/v1/api-keys.
API_KEY_SCAN_ORG_REQUIREDCreate keys with scan scopes under an organization, not the platform.
API_KEY_SCOPE_EXCEEDS_CREATORRequest only scopes your own key or role holds.
API_KEY_TERMINALS_REQUIREDSet terminals to at least one terminal.
API_KEY_TERMINALS_UNUSEDRemove terminals, or add the scans:write scope.
EXPIRY_PASTSend a future time in milliseconds.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
VALIDATIONFix each field in issues and resend.
POST/api/v1/api-keys
api-keys:writeSDK pb.apiKeys.create

Body

orgIdstring | null · max 64Required
namestring · max 120Required
kind"service" | "personal" | "platform"
scopes"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"org_admin" | "integration_admin" | "template_author" | "template_reviewer" | "template_publisher" | "pass_operator" | "read_only"[]
ipAllowstring · max 60[]
templateIdsstring · max 64[]
passStyles"generic" | "posterGeneric" | "storeCard" | "coupon" | "eventTicket" | "boardingPass"[]
terminalIdsstring · max 64[]
mode"live" | "test"
expiresAtinteger | null · ≥ 0

Returns

201 ApiKeyMinted

Errors

CodeStatusFix
API_KEY_CHILD_CANNOT_MINTCreate the key with the original parent key or from a signed-in session.
API_KEY_CHILD_WIDERRequest only scopes the parent key already holds, or create the key with a broader parent.
API_KEY_MODE_MISMATCHCall the rotate endpoint with a key in the same mode as the key you rotate.
API_KEY_NOT_FOUNDLook up the id with GET /api/v1/api-keys, using a key of the same mode.
API_KEY_NOT_ROTATABLECreate a new key with POST /api/v1/api-keys instead of rotating this one.
API_KEY_PARENT_RETIRINGCreate the key with a key that is not retiring.
API_KEY_REQUIREDCall it with Authorization: Bearer $PASSBOOK_KEY.
API_KEY_RESTRICTED_ROUTECall this route with a key that has no template restriction.
API_KEY_RESTRICTION_UNSUPPORTEDSet templates and styles only on organization keys that hold pass, holder, template or NFC scopes.
API_KEY_RETIRE_SETLeave the key as it is, or create a replacement with POST /api/v1/api-keys.
API_KEY_SCAN_ORG_REQUIREDCreate keys with scan scopes under an organization, not the platform.
API_KEY_SCOPE_EXCEEDS_CREATORRequest only scopes your own key or role holds.
API_KEY_TERMINALS_REQUIREDSet terminals to at least one terminal.
API_KEY_TERMINALS_UNUSEDRemove terminals, or add the scans:write scope.
EXPIRY_PASTSend a future time in milliseconds.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
VALIDATIONFix each field in issues and resend.
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.

api-keys:writeSDK pb.apiKeys.retire

Path

idstring · max 64Required

Body

orgIdstring | null · max 64Required
retireAtinteger · ≥ 0Required

Returns

200 ApiKeyRetired

Errors

CodeStatusFix
API_KEY_CHILD_CANNOT_MINTCreate the key with the original parent key or from a signed-in session.
API_KEY_CHILD_WIDERRequest only scopes the parent key already holds, or create the key with a broader parent.
API_KEY_MODE_MISMATCHCall the rotate endpoint with a key in the same mode as the key you rotate.
API_KEY_NOT_FOUNDLook up the id with GET /api/v1/api-keys, using a key of the same mode.
API_KEY_NOT_ROTATABLECreate a new key with POST /api/v1/api-keys instead of rotating this one.
API_KEY_PARENT_RETIRINGCreate the key with a key that is not retiring.
API_KEY_REQUIREDCall it with Authorization: Bearer $PASSBOOK_KEY.
API_KEY_RESTRICTED_ROUTECall this route with a key that has no template restriction.
API_KEY_RESTRICTION_UNSUPPORTEDSet templates and styles only on organization keys that hold pass, holder, template or NFC scopes.
API_KEY_RETIRE_SETLeave the key as it is, or create a replacement with POST /api/v1/api-keys.
API_KEY_SCAN_ORG_REQUIREDCreate keys with scan scopes under an organization, not the platform.
API_KEY_SCOPE_EXCEEDS_CREATORRequest only scopes your own key or role holds.
API_KEY_TERMINALS_REQUIREDSet terminals to at least one terminal.
API_KEY_TERMINALS_UNUSEDRemove terminals, or add the scans:write scope.
EXPIRY_PASTSend a future time in milliseconds.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
VALIDATIONFix each field in issues and resend.

Activity

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.

api-keys:writeSDK pb.apiKeys.activity.list

Path

idstring · max 64Required

Query

limitinteger · ≥ 1 · ≤ 100

Returns

200 ApiKeyActivity

Errors

CodeStatusFix
API_KEY_CHILD_CANNOT_MINTCreate the key with the original parent key or from a signed-in session.
API_KEY_CHILD_WIDERRequest only scopes the parent key already holds, or create the key with a broader parent.
API_KEY_MODE_MISMATCHCall the rotate endpoint with a key in the same mode as the key you rotate.
API_KEY_NOT_FOUNDLook up the id with GET /api/v1/api-keys, using a key of the same mode.
API_KEY_NOT_ROTATABLECreate a new key with POST /api/v1/api-keys instead of rotating this one.
API_KEY_PARENT_RETIRINGCreate the key with a key that is not retiring.
API_KEY_REQUIREDCall it with Authorization: Bearer $PASSBOOK_KEY.
API_KEY_RESTRICTED_ROUTECall this route with a key that has no template restriction.
API_KEY_RESTRICTION_UNSUPPORTEDSet templates and styles only on organization keys that hold pass, holder, template or NFC scopes.
API_KEY_RETIRE_SETLeave the key as it is, or create a replacement with POST /api/v1/api-keys.
API_KEY_SCAN_ORG_REQUIREDCreate keys with scan scopes under an organization, not the platform.
API_KEY_SCOPE_EXCEEDS_CREATORRequest only scopes your own key or role holds.
API_KEY_TERMINALS_REQUIREDSet terminals to at least one terminal.
API_KEY_TERMINALS_UNUSEDRemove terminals, or add the scans:write scope.
EXPIRY_PASTSend a future time in milliseconds.
FORBIDDENUse a key with the scope the operation lists, or ask an org admin.
INVALID_API_KEYCreate a new key in the console and update PASSBOOK_KEY.
MISSING_SCOPECreate a key with the scope the operation lists under security.
NOT_FOUNDCheck the id, and that the key's mode (test or live) matches the object.
ORG_NOT_FOUNDCheck orgId with GET /api/v1/orgs.
RATE_LIMITEDWait for Retry-After seconds, then retry. Back off on repeats.
UNAUTHENTICATEDSend Authorization: Bearer $PASSBOOK_KEY.
VALIDATIONFix each field in issues and resend.