API Documentation — PassEngine

Authentication

All API requests require a valid API key sent in the Authorization header. API keys can be created in the Dashboard → API section (Pro plan, admin only).

Authorization: Bearer 2pk_your_api_key_here

Base URL

https://your-domain.com/api/v1

POST /api/v1/passes — Create a Pass

Request Body

Field	Type	Required	Description
`type`	string	Yes	`"single"` or `"multi"`
`name`	string	No	Human-readable label
`note`	string	No	Internal note (not shown on public page)
`maxUsages`	number	No	Max scan count for multi passes (null = unlimited)
`validFrom`	string	No	ISO 8601 date (e.g. `"2025-06-01T00:00:00Z"`)
`validUntil`	string	No	ISO 8601 date
`customFields`	array	No	Array of `{ "key": "...", "value": "...", "isPublic": true }`
`templateId`	string	No	Pass template ID for styling

Response (201 Created)

{
  "id": "clx1abc...",
  "code": "AbCd1234EfGh",
  "name": "VIP Guest",
  "type": "single",
  "status": "active",
  "maxUsages": null,
  "usagesCount": 0,
  "validFrom": null,
  "validUntil": "2025-12-31T23:59:59.000Z",
  "publicUrl": "https://your-domain.com/p/AbCd1234EfGh?token=...",
  "createdAt": "2025-06-01T12:00:00.000Z"
}

Error Codes

Code	Description
`400`	Bad Request — invalid input (e.g. missing type)
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — plan limit reached or not on Pro plan
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error

All errors return JSON: { "error": "message" }

Rate Limits

30 requests per minute per API key
Rate limit headers are included in responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
When rate limited, a 429 response includes a Retry-After header

Examples

curl

curl -X POST https://your-domain.com/api/v1/passes \
  -H "Authorization: Bearer 2pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "single",
    "name": "VIP Guest",
    "validUntil": "2025-12-31T23:59:59Z",
    "customFields": [
      { "key": "Full Name", "value": "John Doe", "isPublic": true }
    ]
  }'

JavaScript (fetch)

const response = await fetch("https://your-domain.com/api/v1/passes", {
  method: "POST",
  headers: {
    "Authorization": "Bearer 2pk_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "single",
    name: "VIP Guest",
    customFields: [
      { key: "Full Name", value: "John Doe", isPublic: true }
    ],
  }),
});

const data = await response.json();
console.log(data.publicUrl);