API documentation for Apple + Google NFC wallet credentials

Install SDK

Authentication

We use a dual authentication mechanism, it consists of two parts:

A static account id to be sent in the X-ACCT-ID header
A shared secret scheme to authenticate every API request with a signed payload in the X-PAYLOAD-SIG header

You can find both keys in your AccessGrid console on the API keys page. If you're logged in, they're automatically embedded into this documentation.

Otherwise, the code samples below reference your account id as $ACCOUNT_ID and your shared secret as $SECRET_KEY. Substitute them inline, or export them in your shell before running a snippet:

export ACCOUNT_ID="<your account id>"
export SECRET_KEY="<your shared secret>"

The shared secret scheme works as follows…

Grab your shared secret from the API keys page in the AccessGrid console.

For every request that you make, you'll use your shared secret as the salt with a base64 encoded version of your payload as the input to a SHA256 hashing function. When there is no payload, simply use this JSON as the payload (like in suspend, unlink, and resume calls) or sig_payload param for GET requests (replacing the value with the appropriate id, such as the card id or card template id for enterprise calls): {"id": "0xc4rd1d"}

You'll then need to use this SHA256 hash as the value for the X-PAYLOAD-SIG header in your request. From a high-level, the code needed to create the signature is as follows: SHA256.update(shared_secret + base64.encode(payload)).hexdigest()

If you use one of our SDKs, this will all be handled for you!

Rate Limits

API requests that provision Android passes (Google Wallet) are subject to rate limits based on Google's Wallet API guidelines. When issuing or updating Android passes, please observe the following limits:

Maximum of 5 concurrent connections per account
Maximum of 20 requests per second per account

These limits apply to operations that trigger Google Wallet API calls, including issuing new Android passes and updating existing ones. Requests exceeding these limits may be throttled or rejected.

Guides

Tools

Case studies

Employee badges

Multi-family keys

Hotel keys