Authentication
Exchange your client ID and secret for a one-hour access token, then send it with every request.
Switched on per organisationThis is built and working, and is switched on for each organisation on request. Ask your account manager, or reply to any email from us naming it.
The API uses OAuth 2.0 client credentials. Your system exchanges its client ID and secret for an access token, then sends that token with every request.
Get a token
POST /v1/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials{ "access_token": "atgt_...", "token_type": "Bearer", "expires_in": 3600, "scope": "employees:read holidays:read leave:read" }Send the client ID and secret with HTTP Basic (recommended), or as client_id and client_secret in the form body, never both. Add scope=employees:read (or another scope) to ask for less than the credentials allow.
Use the token
Send it with every request as Authorization: Bearer atgt_.... A token lasts one hour. Reuse it until it expires rather than asking for a new one per request, and ask for a new one when you get a 401.
Good to know
- Credentials and tokens in the URL are refused.
- The API sends no cross-origin headers, so call it from a server or a script, never from code running in someone's browser on another site.
- Token requests are limited to 10 a minute per set of credentials.
- The token endpoint reference lists every error it can return.