Authentication

One bearer header, and a key that holds companies and field groups.

Authorization: Bearer atk_live_…

An administrator with the Integrations permission creates keys under Settings, Integrations, API keys in the andteam console. The secret is shown once, when the key is created or rolled. andteam stores only a hash of it, so nobody, including andteam, can show it to you again. Lose it and you roll the key.

The examples in the API reference send the key as a bearer token. Put yours where each example’s placeholder is, or into the playground’s authorization field to send a request from the page.

​

What a key holds

A key is one credential with four settings. Each is chosen when the key is created and can be changed later.

Setting	What it does
Companies	All the tenant’s companies, or the ones you name. A key reads only those. Asking for another company’s record answers company-not-allowed.
Field groups	Which fields the key may read: Directory, Organisation, Positions, Time off, Personal contact, Personal details and Special categories. A new key has Directory and Organisation. See Field groups.
Allowed IP range	Optional. An address range such as 196.22.0.0/16. A request from outside it answers ip-not-allowed.
Expiry	90 days, 1 year (the default), 2 years or none. Past it, the key answers expired-key. andteam reminds your administrators before it expires.

Give each system its own key. A payroll feed, an IT directory and a rostering tool then each read only what they need, can each be revoked on their own, and are each counted on their own against the rate limit.

​

Special categories

Race and EE designation, disability and medical aid membership are special personal information. A key that asks for them states why, and the Information Officer approves before they are readable. Until then the key keeps working with its other groups. A key that asked for nothing else is inactive, and answers pending-approval, until the approval. See Special categories.

​

Rolling a key

Rolling gives the key a new secret, shown once. The old secret keeps working for 24 hours, so you can swap it in your system at any moment in that window without an outage. After 24 hours it answers rolled-key-expired. Rolling a key that was already rolled ends the earlier secret at once.

​

Revoking a key

Revoking is immediate and final. From that moment the secret answers invalid-key (or revoked-key), because a revoked key’s secret is no longer recognised. Create a new key for the system instead.

​

Sandbox tenants

A sandbox tenant does not create keys: its data never leaves andteam. See The sandbox.

​

When authentication fails

Status	Type	Cause
401	missing-key	No Authorization: Bearer header.
401	invalid-key	The secret is not one andteam knows, or was revoked.
401	revoked-key	The key has been revoked.
401	expired-key	The key is past its expiry date.
401	rolled-key-expired	The secret was rolled and its 24 hours are over.
403	pending-approval	The key is waiting for the Information Officer.
403	ip-not-allowed	The request came from outside the key’s allowed range.

A 401 carries WWW-Authenticate: Bearer realm="andteam". See Errors for every type.