Authentication - Cotality developer portal

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

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.

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.

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.

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:

Use your client_id and client_secret as HTTP basic auth credentials to request an access token from the token endpoint
Extract the access_token from the response
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`

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:

{
  "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 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.

Requesting a new token does not reset your request quota. The quota is counted per client_id — see Rate limits.

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.

​Choosing an authentication flow

Machine-to-machine

User-to-service

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

​Machine-to-machine (client credentials)

​Getting a token with client credentials

​Step 1: Request an access token

​Step 2: Extract the access token

​Step 3: Use the token

​Token expiry

​What your token can access

Choosing an authentication flow

User-to-service (authorization code with PKCE)

Machine-to-machine (client credentials)

Getting a token with client credentials

Step 1: Request an access token

Step 2: Extract the access token

Step 3: Use the token

Token expiry

What your token can access