# Authenticating requests

Every authenticated endpoint takes the same header:

```bash
Authorization: Bearer {YOUR_API_TOKEN}
```

Tokens are issued from **Settings → API tokens** inside the CRM. The plain text
is shown **once, at creation**; after that the CRM only keeps a hash, so there
is no screen anywhere that can show it to you again. If you lose it, issue
another one and delete the old.

A token belongs to a person, not to a company. It can do what that person can
do, and nothing more: every policy in the CRM still applies on top of the
checks below.

## Which location does a token act on?

This is the question that causes most of the surprises, and the answer has two
branches.

A CRM account can hold several **locations** — teams, offices, branches. Data
never crosses between them: a contact belongs to exactly one location, and a
request only ever sees the location it is acting on.

| How the token was created | The location it acts on |
|---|---|
| **Bound to a location** (you picked one when creating it) | That location. Always, for the life of the token. |
| **Not bound** | Whatever location that person has open in the CRM right now. |

> **Bind your integration tokens.** An unbound token follows the person who
> owns it: the day they switch to another team in the web interface, your
> integration starts writing there too, with no error and no warning. It is the
> one failure in this page that is silent.

You do not send the location on a request. There is no `location_id` parameter
and no header for it — the token decides, which is what makes it impossible for
one integration to reach into another team's data by changing a payload.

## Abilities

An ability answers *what* this token may do, and *where*. Three shapes are
accepted, from widest to narrowest:

| Ability | Means |
|---|---|
| `*` | Everything, everywhere the person can reach. This is what the token screen issues today. |
| `location:{id}:*` | Everything inside one location. |
| `location:{id}:{ability}` | One ability inside one location. |

Endpoints that check an ability say so in their group. Today that is the
**Negocios y Cotizaciones** group, which requires `quotes` — so a narrow token
for a billing integration would carry `location:42:quotes` and nothing else.

Everything else accepts any valid token belonging to a person who is allowed to
do it.

## When a person belongs to several locations

Nothing changes about the token itself: it still belongs to the person, and it
still acts on one location at a time. What changes is which one.

- **One token per location** is the shape that works. Create one bound to each
  location and give each integration the one it needs. The two never see each
  other's data.
- **One unbound token for everything** does not work, and the reason is above:
  the location follows the human, not the integration.

## Rotating a token

Tokens can be given an expiry when they are created (1 to 3650 days). Expired
or deleted tokens stop working immediately — there is no grace period — so
rotate in this order:

1. Create the new token, bound to the same location.
2. Deploy it to your integration.
3. Delete the old one from the same screen.

Doing it the other way round is an outage, not a rotation.

## Reading a failure

| Code | What happened | What to do |
|---|---|---|
| `401` | No token, a token that does not exist, or one that has expired. | Check the header. If it looks right, the token was deleted or expired: issue a new one. |
| `403` | The token is valid, but this action is not allowed — either the person cannot do it, or the token lacks the ability **in this location**. | Read the message: it names the ability that was missing. |
| `404` | The record exists, but not in this token's location. | Not a mistake in your call — it is the location boundary. See [Errors](/docs/guides/errors). |

A `404` where you expected a `403` is deliberate: answering "forbidden" would
confirm that a record exists in a location you cannot see.

## The CRM's own screens do not use tokens

The web interface authenticates with a session, not with a Bearer token, and
that is why the ability checks above never get in its way. It also gets its own
request budget: a token is limited per token, the interface per session. The
numbers are in the [introduction](/docs).