Provisioning API Keys
Mint, scope, and revoke credentials for the Agent Provisioning API.
Overview
The Agent Provisioning API lets external systems create and configure agents programmatically. Because that API has no way to mint its own credentials, an IT Admin has to create keys from the console - this page is the only way to get one. Every key you mint is tied to your tenant and carries a ceiling: the set of scopes, tool access, outbound channels, and cost caps it is allowed to use. Anything requested through the Provisioning API with a given key is checked against that key's ceiling.
Accessing Provisioning API Keys
Navigate to Administration > Account > Provisioning API Keys.
This page requires the settings:read permission.
Minting a Key
- Click Mint New Key.
- Enter a Key Name - a short, human-readable label (e.g., "Fleet onboarding automation") so you can tell keys apart later. This is the only field required to mint a key.
- Select the Scopes this key needs, using the Scopes table below. Nothing is pre-selected, and a request made with a scope the key does not carry is rejected with
403. - Optionally widen the ceiling before minting:
- Tool ceiling - which agent tools this key is allowed to invoke.
- Mailbox binding - whether an agent minted with this key may be bound to a mailbox.
- Outbound channels - Email, Teams, and Slack each have their own reach setting (None, Internal, Any).
- Knowledge source kinds and review policies - which knowledge sources and human-review gates the agent may use.
- Autonomy levels - which autonomy settings (
investigate_only,approve_all,auto_low,auto_medium,full) an agent provisioned with this key may be given. Tick only the levels this integration actually needs; a key mints with none of them permitted. - Allow SME agent creation - whether this key may provision an agent as a Subject Matter Expert. An SME becomes a callable tool that other agents can invoke, so it is granted per key in the same way as mailbox binding, and a key mints with it off.
- Max Daily / Max Monthly Usage Cost ($) - spending caps for agents minted or configured with this key.
- Optionally set an Expires date.
- Click Mint Key.
Scopes
Every scope a provisioning key can carry, and what selecting it allows:
| What selecting it allows | Scope |
|---|---|
| Create an agent through the Provisioning API | agents.provision |
| Configure an agent's tools | agents.tools |
| Bind an agent to a mailbox | mailboxes.bind |
| Attach and manage an agent's knowledge sources | knowledge.manage |
| Configure an agent's escalation policy | escalation.configure |
| Read a package back from the API | packages.read |
| Let an apply remove resources the package no longer declares | packages.prune |
Read the discovery surface - GET catalog/tools, GET catalog/knowledge-bases, and GET catalog/package-schema | catalog.read |
| Create and configure grounded knowledge indexes | knowledge.indexes.write |
| Register and update the knowledge sources that feed an index | knowledge.sources.write |
| Trigger a sync of an existing knowledge source | knowledge.sync |
The three knowledge scopes are separate for the same reason packages.prune is separate from the write scopes: standing up a new index, registering a source against it, and re-running a sync are three different blast radii, and an automation that syncs nightly has no business creating indexes. Note that none of them confers deletion - tearing an index down is refused through the Provisioning API by design, and stays a console action.
All three are live. knowledge.sync authorises the two knowledge-source sync routes, so a key carrying it can start a crawl of any SharePoint knowledge source in this tenant. knowledge.indexes.write and knowledge.sources.write authorise the knowledge-package apply route, which requires one or both depending on what the document declares. Granting a scope early is harmless; granting it late means minting a replacement key, because a key's scope list is written once, at mint.
You can only grant what you hold
Selecting a scope grants a key the authority to do something you could do yourself in the console. So you can only grant a scope whose underlying permissions your own role already carries.
The mint form shows you this before you submit. Each scope lists the permissions it implies underneath its checkbox, and any scope your role does not cover is greyed out, with the permission keys you are missing named there and in the tooltip - Configure an agent's tools without agents:write, for example, is not tickable and says so. Ask for the role grant it names, then mint again.
The form is a signal, not the gate. The check that matters runs on the server when you submit, so a scope you somehow submit anyway is still refused with a 403 naming the scope and the exact missing permission keys (scope_exceeds_minter_permissions). Nothing is created either way, so there is never a partly-minted key to clean up.
This is checked once, when the key is minted. It is deliberately not re-checked on every call the key makes: a key has to keep working through an unrelated change to your roles, and a credential that silently stops working when someone edits a role is worse than one whose grant is a recorded, auditable moment. If an admin later loses a permission, keys they already minted keep their scopes - revoke the key if that is not what you want.
| What you need to hold to grant it | Scope |
|---|---|
agents:write | agents.provision |
agents:write | agents.tools |
mailboxes:write | mailboxes.bind |
agents:write and knowledge:read | knowledge.manage |
escalation:config | escalation.configure |
agents:read | packages.read |
agents:delete | packages.prune |
tools:read and knowledge:read | catalog.read |
knowledge:write and index-knowledge:settings:write | knowledge.indexes.write |
knowledge:write and sharepoint:write | knowledge.sources.write |
sharepoint:write | knowledge.sync |
Where a scope lists two permissions you need both, not either. A tenant admin on the built-in Platform Admin role holds all of them and can grant every scope; the refusal bites custom roles that were given settings:write without the underlying authority.
catalog.read is a separate scope by design, because enumerating every tool your tenant can grant and every knowledge base an agent could attach is reconnaissance-grade data, so packages.read does not imply it and it does not imply packages.read. If your integration discovers what to provision before it provisions it, select this scope too - a key without it gets a 403 on all three catalog routes. Keys minted before this scope existed do not carry it; revoke and re-mint to add it.
The shape of that table is load bearing. api/src/__contract__/platform-layout/app-provisioning-docs-coverage.contract.test.js reads the last cell of every table on this page whose last header cell mentions "scope", and fails CI if the set of scopes it finds differs in either direction from the vocabulary in api/src/utils/auth/provisioning-principal.js. Keep one scope per row, in its own final column, spelled as a backticked literal - do not fold it back into prose. That drift is exactly what left catalog.read undocumented on this page after it shipped.
When a package asks for more than the key allows
The ceiling is checked on every call made with the key, not just at mint time. If a package requests an autonomy level you did not tick, or asks to provision an SME with a key that does not allow it, the request is refused with a ceiling violation naming spec.agent.autonomy.level or spec.agent.sme. A key's ceiling cannot be edited after minting, so widen it at mint time or revoke the key and mint a replacement.
Autonomy levels and SME agent creation are not independent of each other. An SME always runs with an autonomy dial, so a package that enables spec.agent.sme without declaring one is treated as requesting auto_low. A key that allows SME agent creation but permits no autonomy levels therefore refuses every such package, with a violation naming spec.agent.autonomy.level rather than spec.agent.sme. Tick auto_low alongside SME agent creation, or make sure the package declares an autonomy level the key does permit.
Every new key starts narrow
A freshly minted key defaults to the narrowest possible ceiling: no scopes, no tools, no mailbox binding, no outbound access, no knowledge sources, no review policies, no autonomy levels, no SME agent creation, and conservative daily/monthly cost caps. Nothing sensitive is pre-checked for you. If you want a key that can, for example, bind a mailbox or send outbound email, you have to select that explicitly - this deliberate friction is the human checkpoint for the entire Provisioning API, so widen a ceiling only for keys that actually need it.
The mint form always resets to that narrow default whenever you open it, and again after you close it - so a ceiling you widened while exploring the form, then cancelled, never carries over into your next key.
Copying the Plaintext Key
Immediately after minting, the full key value is shown exactly once in a dialog with a copy button. Copy it now and store it somewhere secure (such as a secrets manager) - once you dismiss this dialog, Outermind cannot show you the plaintext again. The list view only ever shows the key's 12-character prefix.
The dialog cannot be dismissed (Cancel, the close button, Escape, and clicking outside are all disabled) while the key is being minted, so you won't accidentally close it before the key value appears.
If you lose a key's plaintext, mint a new key and revoke the old one - there is no way to recover or re-display a lost key.
The Keys List
The list shows, for each key:
- Key Name
- Prefix - the 12-character prefix, safe to display and useful for identifying a key in logs
- Scopes / ceiling summary
- Last Used
- Status - Active or Revoked
Revoking a Key
- Find the key in the list and click the revoke (trash) icon.
- Confirm the revocation.
Revoking a key takes effect immediately: the very next request made with that key is rejected, and any integration relying on it loses access on the spot. Revocation cannot be undone - mint a replacement key if the integration needs to keep working.
FAQ
Can I edit a key's ceiling after minting it? No. A key's ceiling is fixed at mint time. To change what a key can do, revoke it and mint a new one with the ceiling you want.
Can I see a key's plaintext value again later? No. The plaintext is shown once, at mint time, and is never stored or displayed again. Only the 12-character prefix is retained for identification.
What happens to agents already using a revoked key? Any request made with a revoked key is rejected on its next call. Update the integration with a new key before it needs to run again.
Why does a new key start with everything unchecked? This is intentional. Provisioning keys are the human gate for an API that can otherwise create and configure agents unattended. Requiring an admin to explicitly opt into mailbox binding, outbound messaging, and other sensitive capabilities prevents those capabilities from being granted by default.