Skip to main content
Noorle has three distinct issuers of credentials, and conflating them is the most common source of confusion. Start here. They are not interchangeable. A token minted by one gateway does not work on another; a boundary id_token is not a management-API access token. API keys are separate from all three. They are platform-local, never boundary-issued. If the identity boundary is down, sign-in fails but API-key verification keeps working.

​
Which credential do I need?

Start with the simplest thing that meets your requirement. Moving from an API key to OAuth later is a configuration change, not a rewrite.

​
Human sign-in

Sign-in is passwordless. There is no password to set, store, or rotate. The magic link carries an opaque single-use token and no destination. The manual code exists for the cross-device case — you start on a laptop, the mail arrives on your phone. Its alphabet deliberately excludes visually ambiguous characters. Guardrails on that flow: PKCE is required, S256 only. plain is refused, and an omitted method defaults to S256 rather than to plain — stricter than the RFC requires. The boundary advertises exactly one response type (code), one grant type (authorization_code), one signing algorithm (RS256), and one client authentication method (client_secret_basic). There is no device flow and no refresh token at the boundary.
The access_token field in the boundary’s /token response is an inert placeholder. The RS256-signed id_token is the sole carrier of identity. Do not build against that access_token.

​
Sessions

Once signed in, the Portal holds a signed, host-only session cookie. Its lifetime is a sliding 20-hour inactivity window, not a fixed 20-hour lifetime — activity refreshes it. The anchor session at the identity boundary is separate and much longer-lived, which is what lets you return to the Portal without re-entering your email.

​
Principal types

Four kinds of principal exist: User, Service, Agent, and System.
  • User — a person. Authenticates by signing in; may also hold an API key.
  • Service — a service account. Authenticates by API key. This is what a backend integration should be.
  • Agent — an agent acting on its own behalf. Created alongside the agent; the principal id is the agent id.
  • System — the platform itself. Never authenticates.
The boundary mints only service and agent principals on request; human and system are refused at that surface. An agent making an outbound call carries a delegation chain: the agent is the immediate actor, and whoever triggered the run is preserved as a nested claim. Chain depth is capped at 5.

​
Roles

Four account roles, in increasing authority: Restricted, Member, Admin, Owner. They map to authority like this: Explicit grants sit on top of the role and can give a Restricted principal exactly the access it needs. See Roles and Permissions.
Those four are the whole set. There is no “Developer” role.

​
How a request is authorized

Two different questions get asked, in two different places. “May this principal manage this resource?” — the management plane. Handlers do not decide this themselves. They build an identity context at the edge and hand it to a per-resource service, which re-reads role and grants per operation rather than freezing them for the request. An authority denial is 403. A resource that does not exist under the account floor is 404. Validation runs only after authority, so a denied caller cannot use error shapes to probe what exists. “May this agent make this tool call?” — the admission door. Different question, different code path. See Agents.

​
Encryption

​
The audit record

Every autonomy decision is appended to the journal, carrying who acted, who invoked, who resolved a gate if one was raised, the tool, the risk tier, the execution surface, and the decision source. Management-plane denials are journaled through the same event. The Portal exposes this per agent under Audit, with CSV export.

​
Practical guidance

Service accounts, not personal keys

A backend service should authenticate as its own service principal. A key tied to a person breaks when that person’s access changes.

Grants, not role escalation

Needing one extra capability is a reason to add a grant, not to promote a principal to Admin.

Never commit a key

API keys are bearer credentials. Environment variables or a secret manager, never version control.

Revoke, do not wait for expiry

Revocation takes effect immediately. Expiry is optional and most keys do not have one set.
Next: API Keys.