Authenticating requests

Every authenticated endpoint takes the same header:

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:

Create the new token, bound to the same location.
Deploy it to your integration.
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.

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.