Skip to main content

Authentication

The Destiny API authenticates every request with a bearer token supplied in the Authorization HTTP header.

Authorization: bearer eyJ0eXAiOiJKV1...

Obtaining a token​

Log in with a username and password to receive a token.

POST /api/v1/auth/login

{
  "username": "your-username",
  "password": "your-password"
}

On success the API returns 200 OK. The new authorization token is returned in the Authorization response header (it looks like bearer eyJ0eXAiOiJKV1...). The response body contains the authenticated user record.

tip

You can also retrieve the current token with GET /api/v1/auth/token, which returns { "data": { "token": "bearer token_key" } }.

Using the token​

Cache the token and send it in the Authorization header on every subsequent request:

curl https://www.acmdestiny.net/api/v1/tests/ping \
  -H "Authorization: bearer eyJ0eXAiOiJKV1..." \
  -H "Content-Type: application/json"

Token refresh — important​

Tokens rotate

The token is refreshed every few minutes by the API server. Whenever you make a request, inspect the Authorization header on the response. If it contains a new token, update your cache and use the new token on all following requests.

The previous token does not expire immediately — it remains valid for 7 days — but you should always adopt the most recent token returned to you.

A robust client therefore:

  1. Logs in once to get an initial token.
  2. Stores the token.
  3. Sends it on every request.
  4. After every response, checks the Authorization header and, if present, overwrites the stored token with the new value.

Permission checks​

Many resources are scoped to an organisational hierarchy (partner → agency → client). You can verify whether the logged-in user is allowed to perform an action before attempting it:

GET /api/v1/auth/permission/{resource}/action/{action}

For example, to check whether the user may view clients:

GET /api/v1/auth/permission/clients/action/view?partner_id=...&agency_id=...&client_id=...

Other auth endpoints​

EndpointPurpose
POST /api/v1/auth/logoutEnd the current session.
POST /api/v1/auth/password/reset/requestRequest a password reset for an email address.
POST /api/v1/auth/password/resetComplete a password reset.
POST /api/v1/auth/register/completeComplete a new user's registration using a registration token.
POST /api/v1/auth/websentinel/userAuthenticate a logged-in user with the WebSentinel service.

See the full list and exact shapes under Authentication in the API Reference.