> ## Documentation Index
> Fetch the complete documentation index at: https://docs.korve.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent OAuth

> Authorize the CLI and first-party MCP clients with scoped, revocable OAuth 2.1 grants.

Interactive CLI sign-in uses OAuth 2.1 authorization code with PKCE. Run:

```bash theme={null}
korve login
```

The CLI binds a callback to a random port on the literal `127.0.0.1`, creates an S256 PKCE
challenge, opens the Korve authorization page, and waits for the one-time callback. Review the
organization, requested role, and exact operation scopes before approving. The requested grant can
never exceed your current organization role, and owner grants do not exist.

The authorization URL opens Korve's `/agent/authorize` screen. If needed, Korve asks you to sign in
and then returns to the same pending request without approving it automatically. The screen shows
the client, requested role, exact operation scopes, and only the organizations where your membership
can satisfy that role. Allowing the request sends a one-time code and the original state to the
server-bound loopback callback; denying it sends `access_denied`. Your platform session and password
are never sent to the client.

The resulting access token is short lived, and the CLI rotates its single-use refresh token
automatically. The CLI stores the tokens in the separate
`${KORVE_CONFIG_DIR:-~/.config/korve}/oauth-credentials.toml` file, with `0600` permissions on
Unix. Organization, grant, and
API URL metadata stay in `~/.config/korve/config.toml`; OAuth tokens do not. Reusing a refresh token
revokes the entire token family rather than issuing another credential.

## MCP authorization

The public authorization contract recognizes the first-party clients `korve-cli` and `korve-mcp`.
An MCP client that implements protected-resource metadata, authorization-server metadata, dynamic
public-client registration, authorization code with S256 PKCE, and rotating refresh tokens can use
the same flow with audience `mcp`; the issued token is
valid only for that audience and its exact operation-id scopes. The MCP endpoint also accepts a
legacy organization API key as a bearer token. Anonymous clients can still list tools and use
`search`, while `execute` requires a credential.

## Revoke a grant

Agent grants are managed with a signed-in dashboard session, not with the grant being revoked.
Members can list and revoke their own grants; admins can manage all grants in the organization.
Revocation invalidates every access and refresh token in the grant immediately and is idempotent.
Membership removal or demotion below the stored grant role also invalidates the grant on the next
access or refresh attempt.

The session endpoints are:

```text theme={null}
GET    /v1/orgs/{orgId}/agent-grants
DELETE /v1/orgs/{orgId}/agent-grants/{grantId}
```

For non-interactive CI, legacy API-key login remains available:

```bash theme={null}
korve login --org "$KORVE_ORG" --api-key "$KORVE_API_KEY"
```

Prefer OAuth for people and local agents; use a narrowly scoped, separately revocable API key for
unattended CI. Never copy a CLI refresh token into an MCP configuration.