OAuth Primitives

Low-level OAuth 2.0 primitives for discovery, token exchange, and JWT operations.

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

Installation

pip install keycardai-oauth

npm install @keycardai/oauth

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

bundle add keycardai-oauth

Key Exports

keycardai.oauth

Export	Description
`Client` / `AsyncClient`	OAuth client for discovery, registration, token exchange, and impersonation
`TokenResponse`	Parsed token endpoint response
`AuthorizationServerMetadata`	Parsed `.well-known` metadata
`pkce.authenticate`	High-level PKCE login flow with browser launch and loopback callback
`pkce.OAuthCallbackServer`	Local callback receiver for custom PKCE flows
`utils.pkce`	Low-level PKCE code verifier and challenge 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

@keycardai/oauth

Export	Description
`fetchAuthorizationServerMetadata`	Discover OAuth server configuration
`TokenExchangeClient`	RFC 8693 token exchange client, with `impersonate()` for substitute-user exchange
`registerClient`	RFC 7591 dynamic client registration
`authenticate`	High-level PKCE login flow (Node.js only)
`generatePkcePair`	Generate a PKCE code verifier and challenge pair
`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-sdk/oauth

Export	Description
`FetchAuthorizationServerMetadata`	Discover OAuth server configuration
`TokenExchangeClient`	RFC 8693 token exchange client, with `Impersonate()` for substitute-user exchange
`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

Keycardai::OAuth

Export	Description
`TokenExchangeClient`	RFC 8693 token exchange client, with `impersonate` for substitute-user exchange
`TokenVerifier`	Access token verification backed by a caching JWKS keyring
`fetch_authorization_server_metadata`	Discover OAuth server configuration
`register_client`	RFC 7591 dynamic client registration
`authenticate`	High-level PKCE login flow with browser launch and loopback callback
`exchange_tokens_for_resources`	Exchange one subject token for several Resources into an `AccessContext`
`AccessContext`	Non-raising container for per-resource delegated tokens
`PKCE.generate_pair`	Generate a PKCE code verifier and challenge pair
`JWKSKeyring`	JWKS key management with per-issuer caching
`JWTSigner` / `JWTVerifier`	JWT creation and validation
`TokenResponse`	Parsed token endpoint response
`OAuthError`, `InvalidTokenError`	Error types

Quickstart

Discover Authorization Server Metadata

from keycardai.oauth import Client

zone_url = "https://<zone-id>.keycard.cloud"

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

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

const zoneUrl = "https://<zone-id>.keycard.cloud";
const metadata = await fetchAuthorizationServerMetadata(zoneUrl);

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

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

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

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

require "keycardai/oauth"

zone_url = "https://<zone-id>.keycard.cloud"
metadata = Keycardai::OAuth.fetch_authorization_server_metadata(zone_url)

puts metadata.issuer
puts metadata.token_endpoint

Token Exchange

from keycardai.oauth import BasicAuth, Client

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

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

const client = new TokenExchangeClient(zoneUrl, {
  clientId: "<client-id>",
  clientSecret: "<client-secret>",
});

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

console.log(response.accessToken);

The client discovers the token endpoint from the zone URL on first use, so there is no need to call fetchAuthorizationServerMetadata yourself.

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

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

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

fmt.Println(response.AccessToken)

require "keycardai/oauth"

client = Keycardai::OAuth::TokenExchangeClient.new(
  issuer: zone_url,
  client_id: "<client-id>",
  client_secret: "<client-secret>",
)

response = client.exchange_token(
  subject_token: "<user-access-token>",
  resource: "https://api.github.com",
)

puts response.access_token

Impersonation

Mint a token that acts as a specific user who isn’t present. The client authenticates with its own confidential credential and names the user; the SDK builds the substitute-user token and runs the RFC 8693 exchange. See Act on Behalf of Absent Users for the setup and policy requirements.

from keycardai.oauth import Client
from keycardai.oauth.http.auth import BasicAuth

with Client(zone_url, auth=BasicAuth("<client-id>", "<client-secret>")) as client:
    response = client.impersonate(
        user_identifier="troy.barnes@greendale.edu",
        resource="https://api.github.com",
    )
    print(response.access_token)

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

const client = new TokenExchangeClient(zoneUrl, {
  clientId: "<client-id>",
  clientSecret: "<client-secret>",
});

const response = await client.impersonate({
  userIdentifier: "troy.barnes@greendale.edu",
  resource: "https://api.github.com",
});

console.log(response.accessToken);

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

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

response, err := client.Impersonate(ctx, oauth.ImpersonateRequest{
    UserIdentifier: "troy.barnes@greendale.edu",
    Resource:       "https://api.github.com",
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(response.AccessToken)

require "keycardai/oauth"

client = Keycardai::OAuth::TokenExchangeClient.new(
  issuer: zone_url,
  client_id: "<client-id>",
  client_secret: "<client-secret>",
)

response = client.impersonate(
  user_identifier: "troy.barnes@greendale.edu",
  resource: "https://api.github.com",
)

puts response.access_token

Use this flow when a CLI tool, desktop app, or MCP client needs to log a user in through their browser. The authenticate() helper opens the user’s browser at the authorize endpoint, runs a local callback server, and exchanges the authorization code for tokens.

import httpx
from keycardai.oauth.pkce import authenticate

# Hit the protected resource without a token to get the WWW-Authenticate challenge
async with httpx.AsyncClient() as http:
    response = await http.get("<resource-url>")
    challenge = response.headers["www-authenticate"]

token = await authenticate(
    client_id="<client-id>",
    resource_url="<resource-url>",
    www_authenticate_header=challenge,
    scopes=["read:data"],
)
print(token.access_token)

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

const token = await authenticate("<keycard-issuer-url>", { // from Settings → Connection
  clientId: "<client-id>",
  scopes: ["read:data"],
});

console.log(token.accessToken);

authenticate() requires Node.js. It uses node:http and node:child_process to run the local callback server and open the browser.

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

token, err := oauth.Authenticate(ctx, "<keycard-issuer-url>", oauth.AuthenticateRequest{
    ClientID: "<client-id>",
    Scopes:   []string{"read:data"},
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(token.AccessToken)

To start from a resource’s WWW-Authenticate challenge instead of a known issuer, use oauth.AuthenticateFromChallenge.

require "keycardai/oauth"

token = Keycardai::OAuth.authenticate(
  issuer: "<keycard-issuer-url>",
  client_id: "<client-id>",
  scope: "read:data",
)

puts token.access_token