Authentication

Navigo uses two different authentication models — depending on which API you are calling.

Public Lead API — API Key

External providers send an API key on every request via the Authorization header:

Authorization: Bearer <YOUR_API_KEY>

curl

curl https://api.navigo.example/api/v1/public/leads/lead_998123A/ \
  -H "Authorization: Bearer $NAVIGO_API_KEY"

JavaScript

await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.NAVIGO_API_KEY}` },
});

Python

requests.get(url, headers={"Authorization": f"Bearer {os.environ['NAVIGO_API_KEY']}"})

Key format

Keys have the following structure:

lp_live_<prefix>_<secret>
       │       │       └─ secret part (shown only once)
       │       └─ key_prefix (used to identify the key)
       └─ environment marker (live)

Example: lp_live_7f2a91_r3vS6gG8-QzM5h...

:::danger Key security

• The key is shown in full only once, at generation time.
• The system does not store it in plain text — only a hashed version is kept in the database.
• If you lose it, it cannot be recovered — you must generate a new one and revoke the old one.
• Never put the key in frontend code, a git repository, or logs. :::

Management API — JWT + permission

Management endpoints are for system admins only. They require a JWT Bearer token, and the user must hold an admin position:

• IsAuthenticated — a valid JWT token.
• IsAdminOnlyPosition — the user must be in an admin position.

If either requirement is not met, 403 Forbidden is returned.

Authorization: Bearer <JWT_TOKEN>

Rate limiting

The Public Lead API limits the number of requests per key:

Limit	Value
Per minute	60 requests
Per day	2000 requests

When the limit is exceeded, 429 Too Many Requests is returned. In that case:

• Respect the Retry-After header in the response.
• Retry with exponential backoff (for example 1s, 2s, 4s, 8s).

More: Rate limits.

Errors

The most common authentication-related errors:

Status	Reason
401 Unauthorized	Key or token is invalid / expired
403 Forbidden	Insufficient permission (not an admin, or a resource you don't own)
429 Too Many Requests	Rate limit exceeded

Full list: Errors.