# 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](https://cloudevents.io/) specification for event delivery.

Configure webhooks in your [AccessGrid console](/content/console/webhooks/index.html).

### 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)

```json
{
  "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

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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
}