Authentication and scopes

The key

Every request carries the key as a bearer token:

Authorization: Bearer atla_live_Vq3nQmd9tP5xJ0bLwYhR2cA7uEoKsZfG1iHjN4rT8yW

A key is atla_live_ followed by 43 characters. Atla stores only a hash of it; if you lose the key there is no way to see it again, so create a new one.

A key belongs to one organization and acts as an administrator of that organization, limited by its scopes. It cannot see or touch any other organization's data.

Scopes

Scopes are chosen when the key is created and cannot be changed afterwards (create a new key instead). The person creating the key can only grant scopes they hold themselves.

Scope	Lets the key	Routes
Read providers	List providers, their facility assignments and specialties	GET /providers, GET /providers/{id}/facilities, GET /providers/{id}/specialties
Manage providers	Create, update and deactivate providers; assign facilities and specialties. Includes Read providers	POST /providers, PUT/DELETE /providers/{id}, POST/PUT/DELETE /providers/{id}/facilities, POST /providers/{id}/specialties
Read facilities	List facilities, their providers and contacts	GET /facilities, GET /facilities/{id}, GET /facilities/{id}/providers, GET /facilities/{id}/contacts
Manage facilities	Create, update and delete facilities and contacts. Includes Read facilities	POST /facilities, PUT/DELETE /facilities/{id}, POST /facilities/{id}/contacts, PUT/DELETE /facility-contacts/{id}
Read needs, orders and shift events	List and read staffing needs, orders and time-clock events	GET /needs, GET /needs/{id}, GET /orders, GET /orders/{id}, GET /shift-events
Manage needs, orders and shift events	Create and update needs and orders, assign providers, record shift events. Includes the read scope	POST /needs, PUT/DELETE /needs/{id}, POST /needs/{id}/assign, POST /orders, PUT/DELETE /orders/{id}, POST /shift-events, PUT/DELETE /shift-events/{id}

GET /profile is available to every key.

A request to a route outside the key's scopes answers 403 and names the missing scope:

{ "statusCode": 403, "statusMessage": "This API key does not have the \"Manage providers\" scope" }

Anything not in the tables above, such as users, messaging, SMS, billing, documents, reports and settings, is not available to API keys at all and also answers 403.

Expiry and revocation

• Every key has an expiry date, 30 to 365 days from creation. An expired key answers 401.
• An admin can revoke a key at any time in Settings → API keys. A revoked key answers 401 on its very next request.
• Neither can be undone. Create a new key when you need one.

{ "statusCode": 401, "statusMessage": "This API key has expired" }

Audit trail

Each key is backed by its own hidden account inside the organization. Every record a key creates or changes is written to the organization's audit log under that account, named after the key, so an administrator can always tell what an integration did. Keys never appear in the organization's Users list and cannot sign in to the web app or the mobile app.

Rate limits

600 requests per minute per key. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; when you run out you get 429 with a Retry-After header in seconds. Spread bulk work out, or cache reference data such as facilities that changes rarely.