Provisioning at scale
Creating agents and their keys from a pipeline, one call or a hundred.
A key in Navige identifies one agent. That is what makes per-agent spend, per-agent policy and a per-agent kill switch possible — so a fleet of a hundred agents is a hundred keys, and nobody should be creating those by hand.
The provisioning API creates an agent and returns its key in one call, so standing up a fleet is a loop in your deployment pipeline rather than an afternoon in the console.
The provisioning credential
Provisioning uses its own credential, not an agent key. It starts with nvadm_, and an agent nv_ key is rejected outright. Two things about it are worth knowing before you build against it:
- The organisation comes from the credential. There is no
orgIdfield in any request body, so a provisioning key cannot create an agent anywhere but its own organisation. - It is accepted only on these routes. Presenting it to an ordinary customer endpoint does nothing — it is not a more powerful version of an agent key, it is a different key for a different job.
Every call is recorded, including the ones that are refused.
One agent
curl -X POST https://app.navige.ai/api/provisioning/agents \
-H "Authorization: Bearer nvadm_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"billing-reconciler","purpose":"Nightly ledger reconciliation"}'{
"agent": { "id": "018f…", "name": "billing-reconciler" },
"virtualKey": "nv_…"
}A whole fleet
Up to 100 agents in one call. The batch is not one transaction, deliberately: a single bad name in a hundred should not roll back the ninety-nine that worked, because the obvious reaction to that is to retry the whole batch and create duplicates of everything that had already succeeded.
curl -X POST https://app.navige.ai/api/provisioning/agents/bulk \
-H "Authorization: Bearer nvadm_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"agents":[
{"name":"billing-reconciler","externalRef":"svc-114"},
{"name":"support-triage","externalRef":"svc-115"}
]}'{
"summary": { "requested": 2, "created": 2, "failed": 0 },
"results": [
{ "status": "created", "name": "billing-reconciler", "externalRef": "svc-114",
"agent": { "id": "018f…", "name": "billing-reconciler" }, "virtualKey": "nv_…" },
{ "status": "created", "name": "support-triage", "externalRef": "svc-115",
"agent": { "id": "018f…", "name": "support-triage" }, "virtualKey": "nv_…" }
]
}externalRef is echoed back on every result, created or failed. It is how you match a result to your own record without relying on array order.
Read the status code
201— every agent was created.207— some were created and some were not. Readresults.422— none were created.400— the batch was refused before anything was created: empty, over 100, or two items sharing a name.
Why names must be unique within a batch
A batch containing the same name twice is refused outright, before anything is created. Two agents with one name are indistinguishable afterwards, and since each key is shown once, there would be no way to work out which key belonged to which.
If your organisation has an agent cap
Provisioning does not bypass it — it is a different way to authenticate, not a way to exceed a limit. The cap is spent in order: a batch of fifty against ten remaining places creates ten and fails the other forty, each with agent limit N reached against its name. You keep what fitted and know exactly what did not, rather than having the batch refused and working out the remainder yourself.
The apps on a computer connected with navige connect — Claude Code, Codex, Cursor, Copilot CLI, each desktop tool server — appear as agents of their own but do not count toward the cap: they are one connection told apart, not agents anyone chose to add.
Who works here
Two read-only routes for a service acting for people, such as an assistant that receives messages in Lark. Both need a credential carrying the members:read scope.
The organisation's people: memberId, name, email, role (owner, admin or viewer) and whether they are active.
Who an id in another system belongs to. The answer is { "status": "linked", "member": { … } } or { "status": "unlinked" }, both with status 200, so “we do not know this person” is never confused with an error.
What your calls are subject to
Besides the organisation's agents, policies and key prefixes, this returns capabilities: whether guardrails and approvals really stop calls (governanceEnforces), whether the cost levers act (leversAct), whether shadow mode is on, and guardrailsAdvisory, the one answer to act on. Needs state:read. tier says what is billed, not what is enforced: a free workspace can have enforcement granted without becoming a paid one.
Read it when you decide how much an agent may do, rather than once at setup. A grant can be revoked or can expire, and the answer here changes the moment it does. A call made with onBehalfOf is enforced whenever shadow mode is off, whatever guardrailsAdvisory says.
Losing a key
There is no endpoint that returns an existing key, and that is not an omission — keys are stored as a SHA-256 hash, so nobody at Navige can read one either. If a key is lost, mint another:
An agent may hold several keys at once, which is the right shape for the same agent running on several machines: revoke one without disturbing the others. Use /api/agents/{id}/rotate-key instead when you suspect a key has leaked rather than merely been mislaid.