> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/mcp/oauth.md).

# OAuth for MCP clients

Authorization discovery, PKCE, scopes and token handling for MCP client implementers.

Kinesis supports browser-based OAuth authorization for the MCP server. API keys remain available for clients that use a static bearer header.

## Discover the server

An unauthenticated MCP request returns `401` with a `WWW-Authenticate` challenge containing `resource_metadata`. Follow that URL rather than hard-coding deployment-specific authorization endpoints.

For the public service:

| Metadata                | URL                                                                     |
| ----------------------- | ----------------------------------------------------------------------- |
| Protected resource      | `https://mcp.kinesis.network/.well-known/oauth-protected-resource/mcp`  |
| Authorization server    | `https://portal.kinesis.network/.well-known/oauth-authorization-server` |
| MCP resource identifier | `https://mcp.kinesis.network/mcp`                                       |

The protected-resource document lists the authorization server, resource identifier, supported scopes and bearer-header authentication. The authorization-server document lists the endpoints and client capabilities.

## Authorization flow

```mermaid
sequenceDiagram
  participant C as MCP client
  participant M as Kinesis MCP
  participant P as Kinesis portal
  participant U as User
  C->>M: Request without token
  M-->>C: 401 + resource metadata
  C->>P: Discover authorization server
  C->>U: Open authorization URL with S256 PKCE
  U->>P: Sign in, approve scopes and organization access
  P-->>C: Authorization code
  C->>P: Exchange code with verifier
  P-->>C: Access token
  C->>M: Authorization: Bearer access token
  M-->>C: MCP response
```

The supported grant types are `authorization_code` and `refresh_token`; the response type is `code`. PKCE uses `S256`. Public clients use token endpoint authentication method `none`. The server advertises dynamic client registration and client ID metadata document support; use the discovery response to select the approach your client implements.

The public endpoint paths are `/oauth/authorize`, `/oauth/token`, `/oauth/register` and `/oauth/revoke` on the portal origin.

## Scopes and token lifetime

OAuth requests use explicit API scope names, such as `apps:read`, `monitoring:read` and `compute:spend`. OAuth does not issue the `*` full-access wildcard. Request `offline_access` when your client needs a refresh token.

The current implementation uses ten-minute authorization codes, one-hour access tokens and thirty-day refresh tokens. Use returned expiry values as the authority. Refresh tokens rotate; replace the stored token after refresh and serialize concurrent refresh attempts.

A refresh request may repeat `offline_access`. Kinesis removes that OAuth-only scope before checking resource permissions. Omitting `scope`, or supplying only `offline_access`, retains the issued scopes. A nonempty resource-scope list may narrow the grant but cannot add permissions; ungranted scopes return `invalid_scope`.

{% hint style="info" %}
OAuth tokens are scoped to the MCP resource. The REST API does not accept them. Use an API key for REST integrations.
{% endhint %}

## Organization access

A connection acts as its person with their role in each organization. Consent can allow all organizations, including ones joined later, or selected organizations. `whoami.limitedToOrgs` describes the limit and `list_orgs` lists reachable organizations. Organization-level actions use the slug as `org`; project, app and grid actions resolve it from their resource.

Losing membership ends that connection’s access in the organization. A connection limited to chosen organizations cannot create another organization or answer received organization invitations.

An organization may require SSO for browser access. Approving a connection that will reach it requires an allowed browser session; complete its SSO and repeat approval if `sso_required` is returned. Existing connections continue working without renewing browser SSO every 24 hours, until access is otherwise ended. This applies to either the default MCP URL or the [OpenAI profile](/mcp/openai-profile.md).

## Insufficient scope

Kinesis can return an HTTP `403` challenge before a call runs when it can determine that the OAuth connection lacks required scopes. When the scope depends on tool arguments, a tool failure can include an authorization challenge in `_meta["mcp/www_authenticate"]`.

The Organizations release adds `members:read`, `members:write`, `org:write` and `audit:read`. Existing connections do not gain them through token refresh; the user must approve them again. `audit:read` is required separately for the audit log and is not implied by `org:write`.

Read `structuredContent.error.requiredScopes`, request the appropriate authorization step-up and retry only after the new grant is available. The original user's role on the resource still limits what the connection can do.


---

# 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.kinesis.network/mcp/oauth.md?ask=<question>&goal=<user_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.