circle-exclamation
This documentation is currently under development. Certain sections are not yet complete and will be added shortly.
search
HomeDocumentation

ApplePass

hashtag
Return serial numbers updated since the provided tag for a given device and pass type.

get
/api/{tenantId}/passes/apple/{version}/devices/{deviceIdentifier}/registrations/{passTypeIdentifier}

Called by Apple Wallet to poll for pass updates. Implements the PassKit protocol endpoint for retrieving modified pass serial numbers since a given timestamp.

hashtag
Update Tag (Modification Timestamp)

The tag parameter represents the last modification timestamp the client knows about:

  • When provided: Returns only passes modified after this tag

  • When omitted: Returns all registered passes for the device/type combination

  • When no updates exist: Returns 204 No Content

hashtag
Timestamp Format Evolution

  • Legacy format (before 2024-10-07): Seconds since Unix epoch

  • Current format: Milliseconds since Unix epoch The endpoint automatically detects and handles both formats for backward compatibility.

hashtag
Polling Strategy

Apple Wallet uses this endpoint for efficient incremental sync of pass updates without downloading entire pass files.

Path parameters
deviceIdentifierstringRequired

Device identifier used by Apple for authentication.

passTypeIdentifierstringRequired

Apple pass type identifier.

tenantIdstringRequired
versionstringRequired
Query parameters
passesUpdatedSincestringOptional

Optional modification tag (timestamp). When omitted, all registrations are returned.

Responses
chevron-right
200

List of updated pass serial numbers

No content
get
/api/{tenantId}/passes/apple/{version}/devices/{deviceIdentifier}/registrations/{passTypeIdentifier}
No content

hashtag
Register pass installation on Apple device

post
/api/{tenantId}/passes/apple/{version}/devices/{deviceIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}

Called by Apple Wallet when a pass is added to a device. Implements the PassKit Web Service device registration endpoint as specified by Apple's PassKit protocol.

hashtag
Device Registration Flow

When a user adds a pass to their Apple Wallet:

  1. Apple Wallet generates a unique device identifier

  2. The app extracts and sends the push token to this endpoint

  3. The push token enables server-to-device push notifications when pass data changes

hashtag
Push Token Management

The push token is device and pass-specific. It changes when:

  • The device registers the same pass again

  • The app reinstalls

  • Apple infrastructure updates the token

hashtag
Authentication

Apple sends an Authorization header with the pass's authentication token as:

Authorization: ApplePass <authentication-token>

This token must match the pass's expected authentication value.

hashtag
Idempotency

Calling this endpoint multiple times with the same device and pass returns 200 OK for existing registrations, updating the push token. First registration returns 201 Created.

Path parameters
deviceIdentifierstringRequired

Unique identifier of the device.

passTypeIdentifierstringRequired

Apple pass type identifier.

serialNumberstringRequired

Serial number of the pass.

tenantIdstringRequired
versionstringRequired
Body
anyOptional
Responses
chevron-right
200

Device already registered or updated

No content
post
/api/{tenantId}/passes/apple/{version}/devices/{deviceIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}
No content

hashtag
Unregister pass removed from Apple device

delete
/api/{tenantId}/passes/apple/{version}/devices/{deviceIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}

Called by Apple Wallet when a pass is removed from a device. Stops push notifications to that device and cleans up device registration.

hashtag
Unregistration Scenarios

This endpoint is triggered when:

  • User manually deletes the pass from Apple Wallet

  • Device is factory reset

  • App is uninstalled and reinstalled

  • Cloud backup/restore occurs

hashtag
Device Registration Cleanup

  • Removes the device-pass mapping from the registration database

  • No further push notifications sent to this device for this pass

  • Pass can be re-added and re-registered by the user

  • Push token is safely discarded

hashtag
Re-registration

The same device can re-add the pass later, which creates a new registration via the RegisterDevice endpoint with a fresh push token.

hashtag
Authentication

Apple sends the same authorization token used during registration for verification.

Path parameters
deviceIdentifierstringRequired

Unique identifier of the device.

passTypeIdentifierstringRequired

Apple pass type identifier.

serialNumberstringRequired

Serial number of the pass.

tenantIdstringRequired
versionstringRequired
Responses
chevron-right
200

Pass device registration removed

No content
delete
/api/{tenantId}/passes/apple/{version}/devices/{deviceIdentifier}/registrations/{passTypeIdentifier}/{serialNumber}
No content

hashtag
Log messages sent by Apple PassKit.

post
/api/{tenantId}/passes/apple/{version}/log

Endpoint to receive and log diagnostic information sent by Apple's PassKit service. Apple Wallet and PassKit framework send error and diagnostic messages to help debug pass delivery, installation, and update issues.

hashtag
Diagnostic Information

Messages may contain:

  • Pass installation failures

  • Push notification delivery errors

  • Device registration issues

  • Signature validation errors

  • Update retrieval failures

hashtag
Log Format

Request body contains a JSON object:

{
  "logs": [
    "error message 1",
    "error message 2"
  ]
}

hashtag
Server-side Handling

Received logs are:

  • Stored in application logs with ERROR level

  • Associated with the device/pass that sent them

  • Useful for debugging why passes fail to update or install

  • Used for monitoring pass delivery health

hashtag
Use Cases

  • Debug pass installation failures

  • Monitor PassKit framework issues

  • Identify signature validation problems

  • Troubleshoot push notification delivery

Path parameters
tenantIdstringRequired
versionstringRequired
Body
anyOptional
Responses
chevron-right
200

Logs received and processed

No content
post
/api/{tenantId}/passes/apple/{version}/log
No content

hashtag
Retrieve the latest version of a pass for Apple Wallet.

get
/api/{tenantId}/passes/apple/{version}/passes/{passTypeIdentifier}/{serialNumber}

Returns the current pass file in pkpass format. This endpoint supports conditional requests using standard HTTP caching headers to minimize bandwidth usage.

hashtag
Conditional Requests (HTTP Caching)

The endpoint supports If-Modified-Since header for bandwidth optimization. When the pass has not been modified since the provided timestamp, the server returns 304 Not Modified to avoid transferring the pass file.

Path parameters
passTypeIdentifierstringRequired

Apple pass type identifier.

serialNumberstringRequired

Pass serial number.

tenantIdstringRequired
versionstringRequired
Responses
chevron-right
200

Pass file (pkpass) returned

string · binaryOptional
get
/api/{tenantId}/passes/apple/{version}/passes/{passTypeIdentifier}/{serialNumber}

Last updated