Authentication

The Routal API uses API keys to authenticate every request. Keys are scoped to a single organization and grant the same permissions as the user who created them.

How keys are used

Pass your key as the private_key query string parameter on every request:

curl -G 'https://api.routal.com/v2/vehicles' \
  --data-urlencode 'private_key=YOUR_KEY'

For methods that accept a body (POST, PUT), keep private_key in the query string and put the payload in the body:

curl -X POST 'https://api.routal.com/v2/plan?private_key=YOUR_KEY&project_id=...' \
  -H 'Content-Type: application/json' \
  -d '{"label": "Hello"}'

The API does not accept keys in the Authorization header today.

Key format

API keys are random alphanumeric strings prefixed with api_key_ (e.g. api_key_xY7…32 chars). Treat the entire string as the secret — there is no separate "secret part" to extract.

Issuing and managing keys

Create, label, deactivate, and delete keys from the planner dashboard:

planner.routal.com/h/settings/developers/api-keys

Each key has:

• A label you choose (e.g. staging-integration, analytics-readonly) — purely for your own bookkeeping.
• An active flag — when set to false the key is rejected on auth. Useful to temporarily revoke a key without deleting it.
• A created at timestamp.

There is no last_used_at timestamp today — you can't tell from the dashboard when (or whether) a specific key was last used.

You can have multiple keys active at the same time per organization, which makes rotation painless.

Security

• Treat the key like a password. Anyone with the key can read and mutate every plan, route, stop, and vehicle in your organization (across projects the creating user has access to).
• Never commit keys to a repository. Use environment variables (process.env.ROUTAL_API_KEY) or a secret manager (1Password, Doppler, AWS Secrets Manager, Vault).
• Never put a key in a URL that ends up in logs. Most server logs and HTTP intermediaries capture full URLs, including query strings. Where possible, log the path only and redact the query string before persisting it. This is the biggest practical risk of query-string auth.
• Browser-side code is a no-go. A key shipped to a browser is a public key. If you need to call the API from a browser, proxy through your own backend.

Rotation

Rotate keys on a regular cadence (every 90 days is a reasonable default) and immediately if you suspect exposure.

The recommended pattern:

1. Issue a new key in the dashboard. Keep the existing one active.
2. Deploy your services with the new key.
3. Once you're confident nothing is still using the old key (give it a deploy window plus a margin), set the old key's active flag to false from the dashboard. If anything was still calling it, you'll see auth failures — you can re-activate it instantly.
4. After another window passes without re-activations, delete the old key permanently.

This zero-downtime swap works because Routal supports multiple active keys simultaneously per organization.

Permissions and scoping

API keys today are organization-scoped: they can read and mutate every resource the creating user has access to. There is no per-key scoping (read-only vs. read-write, project-level scoping, IP allowlist, etc.).

If your integration only needs read access, isolate it behind your own service layer.

Granular scopes are on the roadmap. If you have a concrete use case, contact us.

What's next

• Quickstart — make your first authenticated call.
• Errors — what happens when a key is missing, malformed, or deactivated. (Spoiler: every API-key auth failure surfaces as highway.apiKey.error.not_found today.)