Authentication and scopes

The token

Every request carries the token in the Authorization header, as Bearer followed by the token:

curl "https://api.nessflow.com/v1/me" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN"

A token belongs to a member and acts for one team. It expires (90 days by default, 365 at most), and it stops working as soon as its holder leaves the team. No cookie, no session: the API is spoken server to server.

A missing, invalid or expired token answers 401 with the unauthenticated code:

curl "https://api.nessflow.com/v1/me" \
  -H "Authorization: Bearer invalid-token"

Scopes

A scope combines a domain and a verb: projects:read, crawls:write, positions:write, webhooks:read… A write scope does not include the read of the same domain. Give each integration only the scopes it needs.

A call without the required scope answers 403 with the token.missing_scope code and the required_scopes list.

Three permissions, always

A call must be allowed by all three at once:

1. the team's plan opens the verb (api.not_in_plan, api.write_not_in_plan);
2. the member's role allows the action (managing webhooks is reserved to owners and admins);
3. the token carries the scope.

Plan refusals name the plan that would lift them (upgrade_to): retrying will not change anything.

Language

Error titles and translated texts follow the Accept-Language header (fr or en, fr by default). Codes are never translated.