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

# Authentication

> How to obtain an access token for Cotality MCP — client credentials for server-to-server integrations, authorization code with PKCE for interactive clients.

Cotality MCP uses OAuth 2.0. Which flow you use depends on how your client authenticates, not on which tools you can reach.

## Choosing an authentication flow

> [card] Machine-to-machine
>
> Backend services, automated pipelines, and MCP clients configured with a static token —
> VS Code, Cursor, Windsurf, or the Python SDK. Uses the `client_credentials` grant.
> **This is the flow described on the rest of this page.**

> [card] User-to-service
>
> Interactive AI assistants that connect on behalf of a person and ship their own OAuth
> client. Uses the `authorization_code` grant with PKCE. Setup is automatic — the client
> discovers Cotality's endpoints for you.

| | User-to-service | Machine-to-machine |
| - | - | - |
| **Grant** | `authorization_code` + PKCE (S256) | `client_credentials` |
| **Credentials** | No client secret — the user signs in with their Cotality identity | `client_id` and `client_secret` as HTTP basic auth |
| **Who is the caller** | The signed-in person | The registered application |
| **Setup** | Automatic — discovered via `/.well-known/oauth-protected-resource` | Manual — request a token and configure it as a header |
| **Attribution** | Requests are attributed to the individual user | Requests are attributed to the application's `client_id` |

Both flows produce a token presented to the same MCP endpoint, and both are subject to the same [rate limits](https://develop.cotality.com/reference/rate-limits.md).

> [!NOTE]
>
> The attribution difference matters for audit and compliance. In the user-to-service flow,
> activity is traceable to a named individual. In machine-to-machine, it is traceable to the
> application only — your own system must record which user triggered a given call.

### User-to-service (authorization code with PKCE)

Use this when an interactive AI assistant connects on behalf of a person. You do not configure endpoints manually: the client reads Cotality's protected-resource metadata, redirects the user to sign in with their Cotality account, and manages token exchange and refresh itself.

| Discovery endpoint | Purpose |
| - | - |
| `/.well-known/oauth-protected-resource` | Advertises the authorization server for the MCP resource (RFC 9728) |
| `/.well-known/oauth-authorization-server` | Advertises the authorization and token endpoints, supported grants, and PKCE methods |

The authorization server supports the `authorization_code` grant with `S256` code challenges and registers clients as public — no client secret is issued or accepted.

> [!NOTE]
>
> This flow is live in both UAT and production. Your client application must be registered with
> Cotality before it can use it — the authorization server resolves the incoming `client_id`
> against its list of permitted clients, and an unregistered `client_id` is rejected with a
> `400`. Contact your Cotality account team to register your client.

### Machine-to-machine (client credentials)

Use this for backend services, automated pipelines, and any MCP client configured with a static bearer token. Your application exchanges its `client_id` and `client_secret` for an access token and sends it as a bearer token. The remainder of this page describes this flow.

***

## Getting a token with client credentials

All requests to Cotality MCP require an access token, which you obtain using your provided `client_id` and `client_secret` OAuth2 credentials. There are three steps:

1. Use your `client_id` and `client_secret` as HTTP basic auth credentials to request an access token from the token endpoint
2. Extract the `access_token` from the response
3. Include the `access_token` as a bearer token on all subsequent requests to Cotality MCP

### Step 1: Request an access token

Send a `POST` request to the token endpoint for your target environment with your credentials as basic auth:

| Environment | Token endpoint |
| :- | :- |
| **UAT** | `https://mcp-uat.cotality.com/oauth/token?grant_type=client_credentials` |
| **Production** | `https://mcp.cotality.com/oauth/token?grant_type=client_credentials` |

```bash theme={null}
curl -X POST "https://mcp.cotality.com/oauth/token?grant_type=client_credentials" \
     -u "<your_client_id>:<your_client_secret>" \
     -H "Content-Length: 0"
```

### Step 2: Extract the access token

The response contains your access token in the `access_token` field:

```json theme={null}
{
  "access_token": "GNdlinr2kVNj3igGI7y176vheYrF",
  "token_type": "Bearer",
  "expires_in": 3599
}
```

### Step 3: Use the token

Include the `access_token` value as a bearer token in the `Authorization` header on your Cotality MCP connection:

```
Authorization: Bearer GNdlinr2kVNj3igGI7y176vheYrF
```

Most MCP clients (VS Code, Python SDK, etc.) accept a bearer token or headers configuration — see [Integration guides](https://develop.cotality.com/mcp/guide.md) for some common client-specific setups.

## Token expiry

Tokens expire after the duration specified in `expires_in` (in seconds). When your token expires, Cotality MCP will reject requests with `401 Unauthorized`. Request a new token using the same process.

> [!WARNING]
>
> Requesting a new token does not reset your request quota. The quota is counted per
> `client_id` — see [Rate limits](https://develop.cotality.com/reference/rate-limits.md).

## What your token can access

An access token carries the scopes granted to your API product. Those scopes determine which tools `tools/list` returns and which tools you may call. Contact your account team to request additional scopes.
