OAuth

The OAuth package provides pure OAuth 2.0 primitives with no MCP dependency. Use it when you need direct control over OAuth flows or are building outside the MCP framework.

When to Use

• Custom OAuth flows outside of MCP
• Token exchange (RFC 8693) for delegated access
• Authorization server discovery
• JWT signing and verification
• Building your own auth middleware

Tip

If you’re building an MCP server, use the keycardai-mcp package instead — it wraps these primitives with MCP-specific middleware.

Installation

Python

pip install keycardai-oauth

TypeScript

npm install @keycardai/oauth

Go

go get github.com/keycardai/credentials-go/oauth

Key Exports

Python

keycardai.oauth

Export	Description
Client / AsyncClient	OAuth client for discovery, registration, and token exchange
TokenResponse	Parsed token endpoint response
AuthorizationServerMetadata	Parsed .well-known metadata
PKCE	PKCE code challenge/verifier utilities
GrantType, TokenType	OAuth enum constants
BearerAuth, BasicAuth	HTTP auth strategies for outbound requests
extract_bearer_token	Utility to extract bearer tokens from headers
OAuthError, TokenExchangeError	Exception types

TypeScript

@keycardai/oauth

Export	Description
fetchAuthorizationServerMetadata	Discover OAuth server configuration
TokenExchangeClient	RFC 8693 token exchange client
JWKSOAuthKeyring	JWKS key management for signing and verification
JWTSigner / JWTVerifier	JWT creation and validation
base64url	URL-safe base64 encoding utilities
HTTPError, OAuthError	Error types

Go

credentials-go/oauth

Export	Description
FetchAuthorizationServerMetadata	Discover OAuth server configuration
TokenExchangeClient	RFC 8693 token exchange client
JWKSOAuthKeyring	JWKS key management with two-level caching
JWTSigner / JWTVerifier	JWT creation and validation
PEMPrivateKeyring	Private key management from PEM-encoded keys
AuthorizationServerMetadata	Parsed .well-known metadata

Quick Start

Discover Authorization Server Metadata

Python

from keycardai.oauth import Client

zone_url = "https://your-zone.keycard.ai"

with Client(zone_url) as client:
    metadata = client.discover_server_metadata()
    print(metadata.issuer)
    print(metadata.token_endpoint)

TypeScript

import { fetchAuthorizationServerMetadata } from "@keycardai/oauth";

const zoneUrl = "https://your-zone.keycard.ai";
const metadata = await fetchAuthorizationServerMetadata(zoneUrl);

console.log(metadata.issuer);
console.log(metadata.token_endpoint);

Go

import "github.com/keycardai/credentials-go/oauth"

zoneURL := "https://your-zone.keycard.ai"
metadata, err := oauth.FetchAuthorizationServerMetadata(ctx, zoneURL)
if err != nil {
    log.Fatal(err)
}

fmt.Println(metadata.Issuer)
fmt.Println(metadata.TokenEndpoint)

Token Exchange

Python

from keycardai.oauth import Client, GrantType

with Client(zone_url) as client:
    response = client.token_exchange(
        subject_token="<user-access-token>",
        resource="https://api.github.com",
    )
    print(response.access_token)

TypeScript

import { TokenExchangeClient } from "@keycardai/oauth";

const client = new TokenExchangeClient({
  tokenEndpoint: metadata.token_endpoint,
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
});

const response = await client.exchange({
  subjectToken: "<user-access-token>",
  resource: "https://api.github.com",
});

console.log(response.access_token);

Go

import "github.com/keycardai/credentials-go/oauth"

client := oauth.NewTokenExchangeClient(
    zoneURL,
    oauth.WithClientCredentials("your-client-id", "your-client-secret"),
)

response, err := client.Exchange(ctx, &oauth.TokenExchangeRequest{
    SubjectToken: "<user-access-token>",
    Resource:     "https://api.github.com",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(response.AccessToken)

Related

SEE ALSO

Authorization (Token Exchange)How Keycard implements RFC 8693 token exchange

Third-Party Tools GuideBuild MCP servers that access external APIs using token exchange

Source

Python SDKkeycardai-oauth

TypeScript SDK@keycardai/oauth

Go SDKcredentials-go/oauth