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

# Authentication

> API keys: format, lifecycle, rotation and revocation

<Info>
  **Quick Summary:** Every request carries `Authorization: Bearer sdb_live_...`. Keys are created by administrators, scoped per resource, bound to an acting person, rotated with an overlap window, and revoked instantly.
</Info>

## The key

A key looks like `sdb_live_` followed by 32 random characters. The prefix identifies the environment that issued the key — production uses `sdb_live_`, a sandbox or staging environment issues its own (for example `sdb_test_`). Only the secret's length and opacity are guaranteed, so never hard-code or validate the prefix in your client. Send the key on every request:

```bash theme={null}
curl https://prod.skillsdbnext.com/api/v1/careers \
  -H "Authorization: Bearer sdb_live_YOUR_KEY_HERE"
```

Only the key first characters and last four are ever displayed again — the full key is shown once at creation and only a one-way hash is stored.

## Scopes and the acting person

A key carries **scopes** in `resource:action` form — `careers:read`, `careers:write`, and so on. `:write` never implies `:read`. Independently, every key is bound to an **acting person**: the API's effective permission is always the intersection of the key scopes and what that person may do in the app. A 403 tells you [which of the two](/api-docs/errors/insufficient-scope) blocked the call.

Scope changes take effect on the **very next request** — nothing is cached.

## Scope reference

Every endpoint's reference page states the scope it needs on its **Requires scope** line. `/ping` is the one scope-free endpoint — any valid key can call it. Remember the intersection rule above: a scope grants nothing the acting person cannot already do in the app — it only ever narrows.

| Scope                  | Grants                                                                                                                                 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `skills:read`          | Read skills, their versions and activity, and skill requests                                                                           |
| `skills:write`         | Create and update skills; create and decide skill requests                                                                             |
| `people:read`          | Read people, their org schema memberships and the reporting structure                                                                  |
| `people:write`         | Create and update people (bulk provisioning included), manage their org schema memberships, manager, email, access level and lifecycle |
| `careers:read`         | Read careers, career types, levels, assignments, distributions, activity and the grading scale                                         |
| `careers:write`        | Author careers and their structure; assign and unassign people                                                                         |
| `training:read`        | Read training records and approval activity                                                                                            |
| `training:write`       | Create and update training records; record approval decisions                                                                          |
| `flags:read`           | Read people flags and skill flags, and who holds them                                                                                  |
| `flags:write`          | Create flags; apply and remove them                                                                                                    |
| `org:read`             | Read the org structure dimensions                                                                                                      |
| `org:write`            | Create and update org structure entries                                                                                                |
| `learning:read`        | Read learning plans                                                                                                                    |
| `learning:write`       | Assign learnings and update learning plan entries                                                                                      |
| `assessments:read`     | Reserved — no endpoint requires it yet                                                                                                 |
| `certifications:read`  | Reserved — no endpoint requires it yet                                                                                                 |
| `certifications:write` | Reserved — no endpoint requires it yet                                                                                                 |

<Note>
  **Note:** The three reserved scopes can already be granted to a key, but no v1 endpoint requires them today. They exist so keys can be provisioned ahead of the assessment and certification endpoints that will use them.
</Note>

## Rotation

Rotating a key issues a replacement (same scopes, same acting person, new secret) while the old key keeps working for an overlap window (24 hours by default). Deploy the new key at your leisure inside the window; the old key stops working when it ends.

## Revocation

Revoking a key stops it **immediately** — the key status is checked live on every request.

## What a 401 means

Any authentication failure returns the same generic [invalid-credential](/api-docs/errors/invalid-credential) problem — the API never reveals whether a key exists, expired, was revoked, or was never valid.