> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/trust-and-security/identity-and-access.md). # Identity and access Four separate identity mechanisms, each scoped to one surface, none falling through to another. Algenta authenticates through four distinct mechanisms depending on which surface a caller is using. They are deliberately separate planes, not four ways of reaching the same check — see [Teams & roles (RBAC)](/deploy-and-operate/teams-rbac.md) for role management once a caller is authenticated, and [Authentication & API keys](/getting-started/authentication.md) for day-to-day setup. | Surface | Mechanism | Falls through to another mechanism on failure? | | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | Engine API (`/v1/*`), Entra-configured gateway | Microsoft Entra ID bearer token | No — an Entra-shaped token that fails verification is rejected outright | | Engine API (`/v1/*`), offline/self-hosted | Locally-verified signed license JWT (signature + expiry, no network call), checked against this deployment's device registry | Falls through only to the API-key path below, for non-JWT credentials | | Engine API (`/v1/*`), hosted or standard self-hosted | Database-backed API key (`X-API-Key` or `Authorization: Bearer`) | — | | Website dashboard (`/v1/account/*`) | Supabase session token (the site's own OAuth session) | No — a separate identity plane from the engine API entirely | ## Entra identity never downgrades When the deployment is Entra-configured and an incoming bearer token is shaped like an Entra token, Entra verification is the *only* path tried. A token that looks like an Entra token but fails verification is rejected — it is never handed to the API-key or offline-license verifiers as a second chance. There is no ambiguity about which identity provider authenticated a given request. ## An Entra identity cannot select its own workspace For every other credential type, a caller may select a workspace via `X-Workspace-Id`. An Entra-authenticated caller's workspace comes only from its provisioned principal mapping — an `X-Workspace-Id` header on an Entra-authenticated request is refused explicitly (`workspace_scope_not_permitted`), not silently ignored. The workspace a person can act in is therefore determined by how their identity was provisioned, not by anything the request itself can claim. ## Offline license verification touches no network A signed license JWT is verified locally — signature and expiry, with no network call. This is what lets a self-hosted, air-gapped deployment keep authenticating requests with the network fully dark. Any credential that is not a recognized license JWT falls back to the database-backed API-key path; a license JWT that fails verification does not. The API server then asks its own device registry whether it still stands behind the license (one indexed lookup, cached up to 30 seconds per server): when the device it names was revoked, its API key was revoked or its member was removed or suspended, the request is refused (`401` `license_revoked`). A license this deployment's registry never issued — a vendor-issued air-gapped license, a deployment license — is governed by the signed revocation list and its expiry instead. A license authenticates a *device*, not a member: it carries the lowest role and never passes a role-gated endpoint, reads the member roster (`GET /v1/team`) or changes the team (`403` `license_principal_not_permitted`). Removing a member revokes their devices: the API refuses their licenses at once, and the signed revocation list carries the revocation to devices running offline. ## The website dashboard is a separate identity plane entirely `/v1/account/*` routes (device management, billing, team, organization settings) authenticate against a Supabase session token — the signed-in user's own OAuth session on the website — not an engine API key. This is deliberate plane separation: an engine API key never grants website dashboard access, and a website session never grants direct API access. ## Next steps * [Authentication & API keys](/getting-started/authentication.md) * [Teams & roles (RBAC)](/deploy-and-operate/teams-rbac.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.algenta.ai/trust-and-security/identity-and-access.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.