# auth.md

How an AI agent authenticates with Sentivel.

## Audience

Agents acting on behalf of a Sentivel user or workspace, over the hosted MCP
server (`https://mcp.sentivel.com/mcp`) or the REST API (`https://www.sentivel.com/api/v1`).

## OAuth 2.1 (preferred)

- Protected Resource Metadata: `https://mcp.sentivel.com/.well-known/oauth-protected-resource`
- Authorization Server Metadata: `https://www.sentivel.com/.well-known/oauth-authorization-server`
- Issuer: `https://www.sentivel.com`
- Scopes supported: `mcp`
- Bearer methods supported: `header`

Dynamic client registration (RFC 7591) is open at `https://www.sentivel.com/oauth/register`. PKCE
(S256) is required. Refresh tokens rotate, and reuse of a rotated token revokes
the whole family.

A user consents at `https://www.sentivel.com/oauth/authorize` and grants a set of workspaces. Access
is the granted set intersected with live membership and the workspace's own
connected-app toggle, re-checked on every request. Leaving a workspace, or an
owner switching the toggle off, makes the connection inert immediately.

## Tokens

For a non-interactive agent, a workspace owner or admin can issue:

- an org token (`sv_…`), bound to one workspace, or
- a personal token (`svu_…`), acting as that user, with the workspace chosen
  per request via the `X-Sentivel-Workspace` header.

Send either as `Authorization: Bearer <token>`.

## Not available to agents

Member invites, member removal, role changes, billing, and a member's own phone
number are human-only by design and are exposed through no token.

Reference: https://docs.sentivel.com