Skip to content

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: request GET https://api.hodeishield.com/.well-known/oauth-protected-resource (unauthenticated). The document (RFC 9728) gives you authorization_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.

  1. Generate a random code_verifier and its code_challenge (SHA-256, method S256 — the only method accepted; plain is rejected).
  2. Open the user's browser at the authorization endpoint with response_type=code, your client_id, redirect_uri, code_challenge, code_challenge_method=S256, and the scope values you need (see below).
  3. 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_uri with a single-use code.
  4. 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 requested offline_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:

  1. Request a device code from the device endpoint with your client_id and the scope values you need. You receive a device_code (for your own use), a user_code (short, to show the human), and a verification URL.
  2. Show the user the user_code and the verification URL, both — as two separate pieces, not only the combined verification_uri_complete link. 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.
  3. 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.
  4. 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 without scope fails with invalid_scope. An empty scope= 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 200 for a token that is unknown, expired or already revoked, so a retry is safe; a public client authenticates with its client_id alone (none in revocation_endpoint_auth_methods_supported). If your client fails to authenticate — an unknown client_id, a disabled client, or a public client that sends a client_secret — the endpoint answers 401 with invalid_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.