Skip to main content
API keys are how software authenticates to Noorle. They belong to API key groups — a named machine principal with its own permission matrix, holding one or more keys so you can rotate without downtime. Create and edit them in the Portal under Settings → API Keys.

​
Creating a group

Create an API key group with a name and an optional description (“What this key group is used for”). Then, inside the group:
  • Keys — mint keys and delete them. Deleting a key requires Admin or Owner.
  • Permissions — a matrix over the account’s agents and gateways.

​
Permissions

Each row in the matrix is one agent or one gateway, and carries:
  • an access level: None, Read, or Write; plus
  • an independent Resolve gate switch, available on agents only.
Rows left at None with Resolve gate off are not stored — the group simply has no authority over that resource. Resolve gate is the authority that lets a non-human caller answer an approval a run raised. It is never implied by anything else; it only exists as an explicit grant on a specific agent.

​
Key format

  • ak- marks the string as a Noorle API key.
  • The access id is 32 hex characters — a UUID with the hyphens removed. It is the public half.
  • The secret follows immediately. It is verified against a stored hash and is shown once, at creation.
A legacy form, ak-{uuid}.{secret}, is still accepted.

​
Using a key

​
Management API — api.noorle.com

Any of these work:
The management API is bearer/API-key only by design — it does not read cookies or session state.

​
MCP gateways — mcp-{handle}.noorle.com

Authorization: Bearer only. No X-API-Key.
The key must belong to the gateway’s account and hold Read on that gateway.

​
Agent gateways — agent-{handle}.noorle.com

Authorization: Bearer with either an API key or a JWT. An API key may invoke an agent over A2A only as a service principal — a key tied to a human user is rejected with 403. The key also needs execute authority on that agent, which is what the Write permission level grants — the picker offers None, Read, and Write rather than a separate execute control.
Write is coarser than its name suggests: it grants read, write, delete, and execute together. A key you granted Write so it could invoke an agent can also delete that agent. There is no narrower level that allows execute without delete.
A 401 comes back with an RFC 6750 WWW-Authenticate: Bearer realm="a2a" header.

​
Rotation

  1. Mint a second key in the same group.
  2. Roll it out.
  3. Delete the old key.
Both keys are live in between; the group’s permissions apply identically to every key it holds.

​
Handling secrets

  • Never commit a key. Never paste one into an issue or a chat.
  • Read it from an environment variable or a secret manager at runtime.
  • One group per integration, so revoking one does not take down the others.
  • Give a group the narrowest matrix that lets it work — Read where Read is enough, and no Resolve gate unless the integration genuinely answers approvals.
There is no per-key rate limit. Rate limiting on the platform is per gateway and per caller, not per key — see MCP gateways.

​
What API keys are not

API keys are platform-side credentials, not identity-boundary tokens. They are created, verified, and revoked entirely within the platform against an existing principal. That means API-key verification keeps working even when interactive sign-in is unavailable. For a human signing in to the Portal, or for CLI-style device sign-in, see the Learn tab’s auth section.

​
Next