REST API setup

Step-by-step walkthrough from "nothing" to "first authenticated call."

1. Get an API account

An API account is a non-human principal that owns one or more bearer tokens and a defined scope of clients and events. Accounts span clients, so they're provisioned by a Jade super-admin from the enterprise admin area — your event organizer can later grant or revoke your account access to specific events from the event's Developers tab.

Ask a Jade administrator for:

  • An API account named for your integration (e.g. "Salesforce attendee sync")
  • The scope you need — which client codes and/or which event codes
  • Whether the account needs access to PII fields (names, emails, addresses)
  • A reasonable rate-limit ceiling (default 60 req/min)

2. Issue a token

Inside the account, the admin clicks Issue token. Jade generates a fresh secret and shows it exactly once in a modal. Copy it immediately — only the SHA-256 hash is persisted, so the plaintext is unrecoverable. If you lose it, an admin issues a new one and revokes the old.

Token format. Tokens start with the prefix jdo_ followed by 32 url-safe base64 bytes. The first 8 characters after the prefix are your "token prefix" — share that freely (it identifies the token in logs) but treat the rest as a secret.

3. Make your first request

Every /v1 call requires the Authorization: Bearer <token> header. 

curl /api/v1/participants \
  -H "Authorization: Bearer jdo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

You'll get back the standard list envelope:

{
  "data": [ /* ... */ ],
  "pageInfo": { "nextCursor": "...", "hasMore": true }
}

4. Confirm your scope is right

Use ?clientCode= and ?eventCode= to narrow within your scope. Naming a value outside your scope returns 403 Forbidden. 

curl "/api/v1/participants?clientCode=acme&eventCode=acme-2026" \
  -H "Authorization: Bearer jdo_..."

5. Wire up incremental sync

For an integration that polls, combine cursors with ?updatedSince=<iso8601> to read only the rows that have changed since your last poll. Cache the ETag on each list response and send it back as If-None-Match on the next call to get a cheap 304 Not Modified when nothing changed. See Pagination & caching for the full pattern.

6. Handle errors consistently

All /v1 errors share one body shape with a machine-readable code you can switch on: 

{
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "details": [ /* per-field issues */ ]
}

See Errors for the full status-code catalog and retry guidance.

Next steps

  • Authentication — token rotation, prefix conventions, error responses.
  • Writing data — POST/PATCH/DELETE patterns, idempotency for financial documents.
  • Webhook setup — receive push notifications when data changes, instead of (or in addition to) polling.
  • API reference — every endpoint and parameter.