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

# Authentication

> Bearer tokens, token types, and what happens when your role changes.

Send your token as a bearer credential. Session cookies are never accepted on
the API host, so a browser session can't be replayed against the API.

```bash theme={"system"}
curl https://api.dueflow.co/v1/members \
  -H "Authorization: Bearer dfp_..."
```

A missing, malformed, expired or revoked token all return the same `401` with
`WWW-Authenticate: Bearer realm="dueflow"` — identical on purpose, so probing
can't distinguish "wrong secret" from "revoked yesterday":

```json theme={"system"}
{
  "error": {
    "code": "invalid_token",
    "message": "The access token is missing, malformed, expired or revoked.",
    "requestId": "pqxl2owuOV26Cf789a6gK"
  }
}
```

## Token types

| Prefix | Type                  | Acts as          | Permissions                                                                  |
| ------ | --------------------- | ---------------- | ---------------------------------------------------------------------------- |
| `dfp_` | Personal access token | You              | Your granted scopes, intersected with your **live** role in the organization |
| `dfs_` | Service token         | The organization | Its granted scopes, intersected with the role assigned at creation           |

Create a personal access token in the dashboard under **Profile → Developer**,
or, if you are an organization admin, a service token under **Settings →
Developers**. The secret is shown once and stored only as a hash — if you lose
it, revoke the token and create another.

Use a service token for anything that has to keep running when a person leaves:
it belongs to the organization rather than to whoever created it, so officer
turnover doesn't break the integration. Its role is fixed at creation and caps
what it can do; admin is not available, so a service token can never change
organization settings or approve reimbursements.

<Warning>
  A personal token's permissions are re-derived on every request. If your role
  is lowered to viewer, write calls start failing immediately; if you leave the
  organization, the token stops working entirely.
</Warning>

## Organization policy

An organization's admins can block scopes for every token they issue, personal
and service alike, under **Settings → Developers**. A blocked scope can't be
requested at creation and is dropped from tokens that already hold it, so a
call that worked yesterday can return `insufficient_scope` today without
anything about your token changing. The effective permissions of any request
are therefore:

```
granted scopes ∩ role ceiling ∩ organization policy
```

The same policy can cap token lifetime below the global maximum.

## Expiry and rotation

Tokens expire — a maximum of 365 days (less if the organization's policy says
so), defaulting to 90. There is no never-expiring option.

We email before that happens: 14 days out and again 3 days out. Personal tokens
notify their owner; service tokens notify the organization's admins, since
nobody owns them.

A service token can be **rotated** from its card in the dashboard. Rotation
issues a successor with the same role and scopes and a new secret, and keeps the
predecessor alive for an overlap window (7 days by default, 30 maximum) so you
can deploy the new secret without downtime. Both work during the overlap; the
old one stops the moment it closes.

Watch the predecessor's `lastUsedAt` on its card during the window — if it's
still being used near the end, something didn't pick up the new secret.

Personal tokens don't rotate: create the replacement, deploy it, revoke the old
one.

## Revocation

Revoking is immediate and permanent. The token row is kept as a tombstone so
that "which token did this?" stays answerable after the fact.