> ## Documentation Index
> Fetch the complete documentation index at: https://docs.andteam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

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

```text theme={null}
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](https://docs.andteam.com/api-reference/directory/list-employees.md) 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](https://docs.andteam.com/concepts/field-groups.md). |
| **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](https://docs.andteam.com/rate-limits.md).

## 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](https://docs.andteam.com/concepts/special-categories.md).

## 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](https://docs.andteam.com/concepts/sandbox.md).

## 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](https://docs.andteam.com/errors.md) for every type.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.