Getting started

• An administrator account on the BeaconCR deployment with access to the API clients page.
• A terminal (or your language of choice) for making HTTP requests.
• The hostname of your BeaconCR deployment — shown below as <host>.

In the admin interface, open Settings → API clients and select New client. Give the client a name that says what it is for (for example “Sponsor data pipeline”), and choose the scopes it needs — each scope grants read or write access to one resource area. Grant the minimum set the integration actually uses; you can always add scopes later.

On creation, the client is issued a client ID and a client secret. The secret is shown exactly once. It is stored hashed on the server and cannot be retrieved again — if it is lost, generate a new one.

Treat the client secret like a password:

• Keep it in a secrets manager or an environment file that is not committed to version control.
• Do not embed it in frontend code, mobile apps, or anything that ships to a browser — this flow is for server-to-server integrations.
• Rotate it if it may have been exposed; rotating immediately invalidates the old secret.

Exchange the client credentials for a bearer token at the token endpoint. The grant type is client_credentials, and the scope you ask for must be a subset of the scopes granted to the client. Token requests are rate-limited like every other endpoint.

curl -X POST "https://<host>/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "scope": "studies:read"
  }'

A successful response looks like this (values are placeholders):

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "studies:read"
}

The access_token is valid for at most one hour (the exact lifetime is in expires_in). There is no refresh token — when a token expires, simply request a new one. See authentication for the full details, including the scope catalogue.

Call GET /organizations/me with the token. It confirms the token works, and shows which organization it is scoped to:

curl "https://<host>/api/v1/organizations/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

A 200 response means you are authenticated and scoped correctly. A 401 means the token is missing, malformed, or expired; a 403 means the token is valid but lacks a scope the call requires — see errors for the response format.

• Browse the interactive API reference for per-endpoint request and response schemas.
• Read pagination before writing list loops, and rate limits before wiring up retries.
• Practice against the sandbox — it is a self-serve organization filled with synthetic data, completely isolated from production studies.