Skip to main content
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. 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

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