OAuth authentication for integrations¶
API key or OAuth?
An API key authenticates a system acting on its own, with the scopes you assign it and no user behind it. OAuth authenticates an integration acting on behalf of a specific HodeiShield user — for example, a CLI that connects with your own session, or an assistant that needs to see exactly what you see and nothing more. If your integration is a service running on its own, use an API key. If it's something a user authorizes to act as them, use OAuth.
What your integration gets¶
A HodeiShield OAuth token is bound to one user and a single tenant: the user chooses, at
the moment of authorizing, which of the tenants they have access to your integration should
operate in. The token never sees more than one tenant, and it is read-only — the same
catalog of /v1 operations, never writes. The one exception is the proposals scope
act:propose, only for the MCP server, which records proposals a person must approve.
1. Discovery¶
Before anything else, your integration needs to know where to send the authorization request. Two paths, depending on what you already have:
- If you only know
api.hodeishield.com: requestGET https://api.hodeishield.com/.well-known/oauth-protected-resource(unauthenticated). The document (RFC 9728) gives youauthorization_servers, with the authorization server's URL. - If you already know the authorization server: request
GET <issuer>/.well-known/oauth-authorization-server(RFC 8414). The document describes every endpoint (authorization, token, revocation, registration), the supported grant types, and the scopes available.
A request to /v1 with no valid credential, or an expired one, responds 401 with a
WWW-Authenticate header pointing at the first of those two documents — that's how your
integration can recover from an expired token without hard-coding the URL.
2. Authorizing: with a browser (code + PKCE)¶
The standard path for any integration with a UI — a CLI, a desktop app, an assistant with an embedded browser.
- Generate a random
code_verifierand itscode_challenge(SHA-256, methodS256— the only method accepted;plainis rejected). - Open the user's browser at the authorization endpoint with
response_type=code, yourclient_id,redirect_uri,code_challenge,code_challenge_method=S256, and thescopevalues you need (see below). - The user signs in if needed, sees the consent screen — what your integration is asking for
and in which tenant — and chooses. HodeiShield redirects to your
redirect_uriwith a single-use code. - Exchange the code for a token at the token endpoint, sending the
code_verifier. You receive an opaque access token (never parse or try to decode it: it is not a JWT) and, if you requestedoffline_access, a refresh token.
If your integration is a public client (with no way to keep a secret — a CLI or a desktop
app almost always is), register it first through dynamic registration
or ask to be given a preregistered client_id.
3. Authorizing: without a browser (device code)¶
For an integration running on a machine with no browser — a server, a container, an SSH session:
- Request a device code from the device endpoint with your
client_idand thescopevalues you need. You receive adevice_code(for your own use), auser_code(short, to show the human), and a verification URL. - Show the user the
user_codeand the verification URL, both — as two separate pieces, not only the combinedverification_uri_completelink. HodeiShield's verification page does not accept a pre-filled code: the user always types it in by hand, on purpose, as proof that the code came from their own screen and not from a link someone sent them. If your client only shows the combined link, the user will land on a blank field and have to go back to read the code off your terminal anyway — show both from the start. - The user opens the verification URL in any browser, signs in, types in the
user_code, sees the same kind of consent screen (what your integration is asking for, in which tenant) and approves. - Meanwhile, your integration polls the token endpoint with the
device_code, at the given interval, until the user approves (or the code expires).
Scopes¶
The scopes a user token can request are read-only: the same <module>:read shape as an
API key (supply_risk:read, compliance.nis2:read, evidence:read…), plus offline_access
if you want a refresh token. No other write scope exists in this catalog — requesting one grants
nothing, it is simply not issued. The exception is act:propose, issued only to the MCP server: it
records proposals that a person in your organisation approves in the console.
The one scope that is not <module>:read is email: GET /v1/me returns user.email only to
a token that carries it, and omits it otherwise (the call is never refused for lacking it).
The consent screen lists it. A client that wants the address must ask for email explicitly:
the default set for a dynamically registered client is the read scopes plus offline_access,
without email.
The authorization server's metadata document lists the scopes available today; see the
/v1 overview for what each scope unlocks.
If you omit scope (RFC 6749 §3.3), both flows behave the same way:
- Browser (code + PKCE): you get the scope set registered for your client. For the
HodeiShield CLI, and for a self-registered client that did not narrow it at registration,
that is every read scope plus
offline_access. - Device code: the HodeiShield CLI gets the same default — every read scope plus
offline_access. Any other client must name its scopes; a device request from another client withoutscopefails withinvalid_scope. An emptyscope=counts as omitted.
Either way the user sees the full list on the consent or verification screen before approving. Asking only for what you need is still the better practice.
Refreshing¶
With offline_access, the refresh token lets you request a new access token without the user
going through the browser again — as long as the user still has access to the tenant they
chose. A refresh token used twice (for example, by duplicated storage) is treated as a sign of
theft and the grant is cut off.
If the user's account is suspended, deleted or deactivated for inactivity, or their
organization is suspended, the refresh (and any pending code or device-code exchange) responds
400 with invalid_grant, and every grant of that user ends. Reactivating the account does
not bring the grant back: the user has to authorize your integration again.
One tenant per token — and what happens if it changes¶
The tenant the user chose when authorizing is re-checked on every request, not only when
the token is issued. If the user loses access to that tenant — it's removed, their role
changes, the account is suspended — your next request with that token responds 401
immediately, without waiting for the token to expire on its own. There is no way to ask for a
token that covers more than one tenant, and no way to change it on a token already issued: if
your integration needs to operate in another tenant, the user has to authorize again and
choose it.
Revocation¶
- From HodeiShield: the user can revoke your integration's access at any time from
My Account › Applications (see below). Revocation is
immediate: the next request with that token, or with its associated refresh token,
responds
401. - From your integration: if your client supports revocation (RFC 7009), send the token to
the revocation endpoint when the user signs out of your integration. It's good practice, not
a substitute for the HodeiShield screen — the user can always revoke from there even if your
integration never calls revocation. As RFC 7009 requires, the endpoint answers
200for a token that is unknown, expired or already revoked, so a retry is safe; a public client authenticates with itsclient_idalone (noneinrevocation_endpoint_auth_methods_supported). If your client fails to authenticate — an unknownclient_id, a disabled client, or a public client that sends aclient_secret— the endpoint answers401withinvalid_client. Revoking a token ends its whole access: the access and refresh tokens and the consent of that integration in that tenant, obtained the same way (browser sign-in or device code). Your integration's accesses in other tenants, or obtained the other way, are not touched — and sending the same token twice does not reach them either.
Signing out of HodeiShield is not the same thing
Signing out of every session of the HodeiShield console does not revoke your integration's OAuth tokens. They are two different credentials with two different lifecycles. If you need to cut an integration's access, do it from Application access.
Errors¶
Any request to /v1 without a valid credential — no token, an expired one, a revoked one, or
one that no longer covers the scope or tenant the request needs — responds 401, with
WWW-Authenticate: Bearer resource_metadata="https://api.hodeishield.com/.well-known/oauth-protected-resource".
A valid token that lacks the scope an operation requires responds 403, with the detail of
which scope was missing — unlike 401, here you know the problem is permissions, not the
credential itself. A valid token whose tenant holds no licence in force (none, suspended,
revoked or expired) also responds 403, with details.code set to LICENCE_INACTIVE: the
same happens with a tenant API key, and it lifts as soon as the licence is renewed. During a
licence's grace period /v1 keeps answering, since everything it serves is a read. A token
whose scope names a module the tenant has not active also gets 403, with details.code
MODULE_NOT_ENTITLED (see Authentication).
MCP clients and dynamic registration¶
If your integration is an MCP (Model Context Protocol) client — an assistant that connects to
HodeiShield's MCP server — you don't need anyone to hand you a client_id in advance: you can
register yourself against the dynamic registration endpoint, unauthenticated, following the
MCP authorization specification. HodeiShield only accepts public clients (no secret) with
the code and refresh grants; any other form of registration is rejected. Your redirect_uris
must be either loopback addresses (a native app or CLI, RFC 8252) or an https:// host
HodeiShield's operator has allow-listed for self-registered clients — an arbitrary https://
redirect is rejected at registration. If your integration is a hosted web client, ask HodeiShield
to add your callback host before you register. The consent screen marks these integrations as
unverified — self-registered, not vetted by HodeiShield — and shows the host it will redirect
to, so the user can spot a client impersonating another one.
Application access¶
Under My Account › Applications, every user sees every access that still holds a valid token: which integration, in which tenant, how it was obtained (browser sign-in or device code), with which scopes, since when, and when the API last accepted one of its tokens (recorded to the minute). From there they can revoke any access — immediate, and it doesn't require the integration to be connected at that moment. Revoking only touches that tenant and that flow: the same integration's access in another tenant, or obtained the other way, stays as it was. An access whose tokens are all gone (for example after the integration signed out) but whose browser consent is still stored is listed as "no active sessions" so you can remove it too.
Some account events end every access of the user at once, with no action in Applications: changing or resetting the password, and an administrator revoking the person's sessions. The integration's tokens stop working and the person signs in again from the CLI or the MCP client. Withdrawing the user from a tenant ends only the accesses bound to that tenant. Signing out of the console, revoking a single console session, removing a passkey or a role change do not end any access: revoke those from Applications.