Authentication
Agent keys, where they go, and why they never collide with a provider key.
One kind of credential: an agent key. It starts with nv_ and names exactly one agent inside one organisation.
nv_kJ2x9Qf4mZ8vR1nT6wY3pL0sD7hB5cA…Where it goes
Three places are accepted, checked in this order.
x-navige-key: nv_…— use this. It is the only one that is unambiguous.Authorization: Bearer nv_…— fine on/enforceand/usage, where nothing else is competing for that header. Not on the LLM proxy.?api_key=nv_…— for MCP clients, whose configuration is a URL with nowhere to put a header.
Bearer sk-… there. If Navige read that header as its own, it would both fail to authenticate you and pull your OpenAI secret into a credential lookup. That is why x-navige-key exists and why it is checked first.How keys are stored
They are not. What is stored is a SHA-256 hash and an eight-character display prefix, which is enough to show you nv_kJ2x… in a list and no help at all to anyone who reads the database.
The consequence is that a key is shown once, at creation, and cannot be recovered. If one is lost, revoke it and mint another.
One key per thing
An agent key is how Navige knows which agent did what. Sharing one across three services makes the audit log, the spend breakdown and every per-agent policy report on a fiction.
It also makes revocation all-or-nothing, which is the worst property to discover during an incident.
Revocation
Revoking is immediate in the database. Key lookups are cached for up to a minute, so a revoked key may be accepted for that long.
If you need an agent stopped now, use the kill switch — it is checked on every call, on every tier, and is not subject to that cache.
Failures
401— no key, a malformed one, or one that does not exist.401— the key was revoked.403— the agent is inactive or past its expiry.
An agent can be given an expiry when it is created. A contractor's integration that stops working on its own is better than one somebody has to remember to turn off.