Identity and SSO

Acahti authenticates people and agents against the instance's user directory. A successful login identifies an account; access to repositories, organizations, Teams, and other services still depends on their own authorization rules.

OAuth for MCP clients#

Use the instance's /.well-known/oauth-authorization-server metadata to find its authorization, token, and registration endpoints. An MCP client registers its callback, uses the authorization-code flow with PKCE S256, checks its own state on return, and exchanges the one-time code using the verifier. The authenticated MCP resource is <instance>/mcp.

The token request includes the registered client_id, and refresh requests include that same ID. Redirects must match a registered URI; native loopback clients may use a different port while keeping the registered scheme, host, path, and query. PKCE verifiers use 43–128 unreserved characters.

Codes expire after five minutes and can be redeemed once. The server currently issues access tokens valid for 90 days and refresh tokens valid for 400 days; read expires_in from the token response and protect both as credentials. First-party web applications use server-configured client identifiers and exact callback URLs. Registration through /oauth/register is for MCP clients and does not create a first-party web application.

OAuth access tokens represent the account's authority. The current mcp scope is not a fine-grained permission grant. Do not send these tokens to another service or assume per-task scope isolation.

The token endpoint accepts the authorization_code and refresh_token grants. The server keeps registered clients, unredeemed codes and refresh tokens in the gateway data directory; access tokens are signed and verified without a stored record.

Shell agents#

Each member creates their own personal Access Token from the avatar menu. In Benchyard set ACAHTI_ROOT_URL and ACAHTI_TOKEN in Secrets, scoped to the instance host. Use the environment directly; host-bound placeholders must not be printed, copied to a file, or forwarded to a different host. See Agent access and CLI.

First-party services#

Phaevo uses a configured callback and a separate 90-second signed identity assertion bound to a challenge and device key, issued at POST /acahti/v1/phaevo/ticket after a live team membership check. Its control plane verifies the assertion and applies its own environment grants. Configuring SSO alone does not grant network access. Consult the Phaevo access documentation for its issuer and gateway configuration.

Account and Team membership changes must be made in Acahti. Protect OAuth client configuration, issuer keys, session secrets, and refresh tokens as credentials. Back up the Acahti data directory as described in How it works before upgrades.