Authentication

Every request to the Navvo integration API is authenticated with an API key. Keys are scoped, rate-limited, and tied to a project inside your organization.

Sending your key

Pass the key on every request using the x-api-key header:

curl "https://navvo.io/api/v1/search?q=pharmacy" \
  -H "x-api-key: nvvo_YOUR_KEY"

For URLs that a browser fetches directly and cannot add headers to — most importantly map tiles and styles in Navvo Maps — pass the key as a query parameter instead. Both api_key and apiKey are accepted:

https://navvo.io/api/v1/tiles/style?style=standard&api_key=nvvo_YOUR_KEY

Key format

Navvo keys are prefixed and easy to recognize:

nvvo_<48 hex characters>

Only a hash of the key is stored server-side, together with the last four characters (for display). The plaintext is returned exactly once, when the key is created.

Scopes

Each key carries a set of scopes. A request to a scoped endpoint succeeds only if the key grants that scope. There are eleven scopes:

New keys are created with eight of the eleven scopes enabled by default. The geo, insights, and optimize scopes are off by default — request them explicitly if your integration needs geofencing, analytics, or optimization.

The live, authoritative list is also available to signed-in developers at GET /developer/scopes (each scope with a label and description).

Obtaining a key

The fastest way to get a key is the Developer Portal at navvo.io/developer — a point-and-click console for organizations, projects, keys, live usage and a request sandbox. Everything below is also available as a REST API if you prefer to automate it.

API keys are created through the developer portal endpoints, which are protected by a user session token (a JWT, not an API key). The flow is: account → organization → project → key. Every organization, project and key is scoped to the user who created it — you only ever see and manage your own.

1. Create an account / sign in

curl -X POST "https://navvo.io/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Your Name",
    "password": "a-strong-password-min-10-chars"
  }'

curl -X POST "https://navvo.io/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "a-strong-password-min-10-chars"
  }'

Both return an accessToken (a Bearer JWT) plus your user and session:

{
  "user": { "id": "uuid", "email": "[email protected]", "name": "Your Name", "roles": ["user"] },
  "sessionId": "uuid",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Send this token as Authorization: Bearer <accessToken> on all /developer/* and /auth/me requests.

2. Create an organization

curl -X POST "https://navvo.io/api/v1/developer/organizations" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Logistics", "slug": "acme-logistics" }'

3. Create a project

curl -X POST "https://navvo.io/api/v1/developer/organizations/<orgId>/projects" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Driver App" }'

4. Create an API key

curl -X POST "https://navvo.io/api/v1/developer/api-keys" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "<projectId>",
    "label": "Driver App – production",
    "plan": "starter",
    "scopes": { "geo": true }
  }'

The response contains your key in the key field — this is the only time it is shown:

{
  "key": "nvvo_3f9c2a1e8b7d6c5f4a3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b",
  "id": "uuid",
  "label": "Driver App – production",
  "lastFour": "9c8b",
  "scopes": {
    "search": true, "geocode": true, "places": true, "routing": true,
    "traffic": true, "telemetry": true, "tiles": true, "imagery": true, "geo": true
  },
  "plan": "starter",
  "quotaPerMinute": 255,
  "quotaPerDay": 100000,
  "unlimited": false,
  "active": true
}

Every key object carries a read-only unlimited boolean. It is true only for a key Navvo has made unlimited. While it is true, the key keeps its quotaPerMinute and quotaPerDay, but they are not enforced. You can't set unlimited through the developer API: like any unknown body field, it is dropped from the request. Contact Navvo if you need an unlimited key.

Request body — POST /developer/api-keys

Managing keys

All of these endpoints require your Authorization: Bearer <accessToken> session token and are scoped to your account.

Disabling vs. deleting

To temporarily turn a key off (and back on), set active:

curl -X PATCH "https://navvo.io/api/v1/developer/api-keys/<keyId>" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

An inactive key is rejected with 403 Forbidden until you re-enable it. DELETE removes the key permanently.

Rotating a key

If a key is leaked or lost, rotate it — this mints a brand-new secret and immediately invalidates the previous one, keeping the same key id, scopes and quotas:

curl -X POST "https://navvo.io/api/v1/developer/api-keys/<keyId>/rotate" \
  -H "Authorization: Bearer <accessToken>"

The response includes the new key in plaintext — again, shown only once. Deploy the new secret to your apps; the old one stops working immediately.

Restricting a key

You can lock a key to the places it is meant to be used from. A key carries two lists. Each list that has entries must match, and an empty list means no restriction of that kind:

Set them in the Developer Portal (API keys → Edit), or with the API:

curl -X PATCH "https://navvo.io/api/v1/developer/api-keys/<keyId>" \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ "restrictions": { "referrers": ["example.com", "*.example.com", "localhost:3000"] } }'

Websites. Write a host, optionally with a port: example.com, app.example.com, localhost:3000. *.example.com covers every subdomain but not example.com itself, so list both when you need both. A scheme or path is accepted and dropped (https://example.com/* is stored as example.com). Without a port, any port matches. A request that names no website is refused. That covers requests with neither Origin nor Referer, such as those from a server, or from a browser whose privacy settings strip both.

IP addresses. Write addresses or CIDR ranges, IPv4 or IPv6: 203.0.113.7, 198.51.100.0/24, 2001:db8::/32.

Each list holds up to 50 entries. In a PATCH:

• a list you leave out keeps its entries;
• [] empties a list;
• "restrictions": null removes both lists.

An invalid entry is refused with 400, and the message names it; nothing is silently dropped. Every key response carries restrictions with both lists, which are empty when the key is unrestricted.

A refused request returns 403 with a code, plus the website or IP address the request came from, so you can tell what to add:

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "KEY_WEBSITE_NOT_ALLOWED",
  "message": "This API key is not allowed from this website",
  "details": { "website": "copycat.example" }
}

Restrictions are checked before scopes and quota, so a refused request does not count against the key's quota. The portal Sandbox runs on Navvo's servers on your behalf and does not apply them.

Errors

See Errors for response bodies and Rate limits for quota details.