API documentation for Apple + Google NFC wallet credentials - AccessGrid

API Documentation

Everything you need to interact with AccessGrid.

Programming Languages

Terminal
JavaScript
Ruby
GO
Python
C#
Java
PHP
Elixir

Webhooks

AccessGrid can send webhook notifications to your server when events occur. Webhooks use the CloudEvents specification for event delivery.

Configure webhooks in your AccessGrid console.

Webhook Configuration

spec_version: CloudEvents specification version (always "1.0")
id: Unique identifier for this event
source: Event source (always "accessgrid")
type: Event type. Possible values:
- Access Pass:
  - ag.access_pass.issued
  - ag.access_pass.activated
  - ag.access_pass.updated
  - ag.access_pass.suspended
  - ag.access_pass.resumed
  - ag.access_pass.unlinked
  - ag.access_pass.deleted
  - ag.access_pass.expired
  - ag.access_pass.renewed
- Access Pass (HID/SEOS only):
  - ag.access_pass.failed
  - ag.access_pass.devices.added
  - ag.access_pass.devices.suspended
  - ag.access_pass.devices.resumed
- Card Template:
  - ag.card_template.created
  - ag.card_template.updated
  - ag.card_template.requested_publishing
  - ag.card_template.published
  - ag.card_template.deleted
- Card Template Pair:
  - ag.card_template_pair.created
- Landing Page:
  - ag.landing_page.created
  - ag.landing_page.updated
  - ag.landing_page.attached_to_template
- Credential Profile:
  - ag.credential_profile.created
  - ag.credential_profile.attached_to_template
  - ag.credential_profile.deleted
- HID Org:
  - ag.hid_org.created
  - ag.hid_org.activated
- Account Balance:
  - ag.account_balance.low
- Webhook:
  - ag.webhook.cert_expiring
data_content_type: Content type of the data payload (always "application/json")
time: ISO 8601 timestamp when the event occurred
data: Event-specific data payload
- access_pass_id: ID of the access pass (for access_pass events)
- card_template_id: ID of the card template (for card_template events)
- landing_page_id: ID of the landing page (for landing_page events)
- credential_profile_id: ID of the credential profile (for credential_profile events)
- account_id: API ID of the account (for account_balance events)
- organization_name: Name of the organization (for account_balance events)
- current_balance: Current balance in dollars (for account_balance events)
- threshold: Low balance threshold in dollars (for account_balance events)
- amount_below_threshold: How far below threshold the balance is in dollars (for account_balance events)
- protocol: Protocol type (desfire, seos, smart_tap)
- metadata: Custom metadata associated with the resource
- device: Device information (for access_pass device events)
- card_number: Card number from credential format, only populated if used directly during issuance
- site_code: Site code from credential format, only populated if used directly during issuance, otherwise 69
- file_data: Hex-encoded credential data, only populated if used directly or via credential pools

Example webhook payload (CloudEvents format)

{
  "specversion": "1.0",
  "id": "unique-event-id-12345",
  "source": "accessgrid",
  "type": "ag.access_pass.issued",
  "datacontenttype": "application/json",
  "time": "2025-01-15T10:30:00Z",
  "data": {
    "access_pass_id": "0xp455-3x1d",
    "protocol": "desfire",
    "card_number": "12345",
    "site_code": "100",
    "file_data": "0A1B2C3D4E5F",
    "metadata": {
      "custom_field": "value"
    }
  }
}

Verify webhook with your endpoint

curl -X POST https://your-server.com/webhooks \
  -H "Content-Type: application/cloudevents+json" \
  -H "User-Agent: AccessGrid-Webhooks/1.0" \
  -d '{
    "specversion": "1.0",
    "id": "test-event-123",
    "source": "accessgrid",
    "type": "ag.access_pass.activated",
    "datacontenttype": "application/json",
    "time": "2025-01-15T12:00:00Z",
    "data": {
      "access_pass_id": "0xp455-3x1d",
      "protocol": "desfire",
      "card_number": "12345",
      "site_code": "100",
      "file_data": "0A1B2C3D4E5F",
      "device": {
        "type": "iphone",
        "id": "device-hash-id"
      }
    }
  }'

Response

Empty

List Webhooks

Retrieve a paginated list of webhooks configured for your account.

Pagination

page: Page number (default: 1)
per_page: Results per page (default: 50, max: 100)

Request

# Build the JSON payload
PAYLOAD="{}"

# Sign the payload
PAYLOAD_B64=$(printf '%s' "$PAYLOAD" | openssl base64 -A)
SIG=$(printf '%s' "$PAYLOAD_B64" | openssl dgst -sha256 -hmac "$SECRET_KEY" -hex | awk '{print $NF}')

curl -G \
-H "X-ACCT-ID: $ACCOUNT_ID" \
-H "X-PAYLOAD-SIG: $SIG" \
--data-urlencode "sig_payload=$PAYLOAD" \
"https://api.accessgrid.com/v1/console/webhooks"

Response

Empty

Create Webhook

Create a new webhook to receive event notifications. URL must be reachable and at least one event must be subscribed.

Fields

name: Webhook name
url: HTTPS endpoint URL
auth_method: 'bearer_token' or 'mtls' (default: 'bearer_token')
subscribed_events: Event names (e.g., 'ag.access_pass.issued')

Request

# Build the JSON payload
PAYLOAD='{"name":"Production","url":"https://example.com/webhooks","subscribed_events":["ag.access_pass.issued"]}'

curl -X POST \
-H "X-ACCT-ID: $ACCOUNT_ID" \
-H "X-PAYLOAD-SIG: $SIG" \
-H "Content-Type: application/json" \
-d "$PAYLOAD" \
"https://api.accessgrid.com/v1/console/webhooks"

Response

Empty

Delete Webhook

Delete a webhook by ID.

Fields

webhook_id: Webhook ID to delete

Request

# Build the JSON payload
PAYLOAD="{}"

curl -G \
-X DELETE \
-H "X-ACCT-ID: $ACCOUNT_ID" \
-H "X-PAYLOAD-SIG: $SIG" \
--data-urlencode "sig_payload=$PAYLOAD" \
"https://api.accessgrid.com/v1/console/webhooks/{webhook_id}"

Response

Empty

Verify Webhook

Trigger verification of a webhook. Webhooks must be verified before they receive event deliveries; verification normally happens automatically when a webhook is created or its URL changes, but this endpoint lets you re-run the handshake on demand.

Fields

webhook_id: ID of the webhook to verify

Request

# Build the JSON payload
PAYLOAD="{}"

curl -X POST \
-H "X-ACCT-ID: $ACCOUNT_ID" \
-H "X-PAYLOAD-SIG: $SIG" \
-H "Content-Type: application/json" \
-d "$PAYLOAD" \
"https://api.accessgrid.com/v1/console/webhooks/{webhook_id}/verify"

Response

// 202 Accepted - verification challenge (re)initiated { "id": "abc123", "verified": false }

// 200 OK - webhook already verified, no action taken { "id": "abc123", "verified": true }