OAuth 2.1

Use OAuth 2.1 for MCP integrations, third-party apps, and server-to-server automation

RevKeen supports OAuth 2.1 alongside API keys. Use OAuth when building MCP integrations, third-party apps, or automated workflows that act on behalf of a merchant.

When to use OAuth vs API keys

Use case	Recommended auth
Server-to-server from your own backend	API key (`x-api-key`)
MCP host (Claude Desktop, Cursor, VS Code)	OAuth (authorization code + PKCE or client credentials)
Third-party app acting on behalf of a merchant	OAuth (authorization code + PKCE)
Automated workflow or CI/CD pipeline	OAuth (client credentials)
Quick prototyping or cURL testing	API key

Supported flows

Authorization Code + PKCE

Best for user-facing integrations where a merchant grants access interactively.

Redirect the merchant to the authorization endpoint
Merchant approves the requested scopes
Exchange the authorization code for tokens

GET https://app.revkeen.com/api/auth/oauth2/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &code_challenge=CHALLENGE
  &code_challenge_method=S256
  &scope=customers:read invoices:read

Client Credentials

Best for server-to-server workflows where no user interaction is needed.

curl -X POST https://api.revkeen.com/api/auth/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=customers:read invoices:read"

Dynamic Client Registration

MCP hosts that support RFC 7591 can auto-register as OAuth clients:

POST https://api.revkeen.com/api/auth/oauth2/register

Token lifecycle

Token	Lifetime	Notes
Access token	1 hour	Prefix: `rk_oauth_*`
Refresh token	7 days	Use to obtain new access tokens

Access tokens are sent via the Authorization header:

Authorization: Bearer rk_oauth_xxxxxxxx

SDK examples

TypeScript

import { RevKeenClient } from '@revkeen/sdk';

const client = new RevKeenClient({
  oauth: {
    clientId: process.env.REVKEEN_CLIENT_ID!,
    clientSecret: process.env.REVKEEN_CLIENT_SECRET!,
    scopes: ['customers:read', 'invoices:read'],
  },
});

const customers = await client.customers.list();

The SDK handles token acquisition, caching, and refresh automatically via OAuthTokenManager.

Go

client := revkeen.NewClient(
    option.WithOAuth(revkeen.OAuthConfig{
        ClientID:     os.Getenv("REVKEEN_CLIENT_ID"),
        ClientSecret: os.Getenv("REVKEEN_CLIENT_SECRET"),
        Scopes:       []string{"customers:read", "invoices:read"},
    }),
)

cURL

# 1. Get access token
TOKEN=$(curl -s -X POST https://api.revkeen.com/api/auth/oauth2/token \
  -d "grant_type=client_credentials" \
  -d "client_id=$REVKEEN_CLIENT_ID" \
  -d "client_secret=$REVKEEN_CLIENT_SECRET" \
  -d "scope=customers:read" | jq -r '.access_token')

# 2. Use it
curl https://api.revkeen.com/v2/customers \
  -H "Authorization: Bearer $TOKEN"

Scopes

Scopes follow {resource}:{action} format. Request only the scopes your integration needs.

Pattern	Meaning
`customers:read`	Read customer data
`invoices:write`	Create and manage invoices
`subscriptions:*`	Full subscription access
`*`	All scopes (avoid in production)

See the full scope table in the API Reference.

Well-known endpoints

Endpoint	URL
OAuth Authorization Server Metadata (RFC 8414)	`https://api.revkeen.com/.well-known/oauth-authorization-server`
OpenID Connect Discovery	`https://api.revkeen.com/.well-known/openid-configuration`
MCP OAuth Metadata	`https://api.revkeen.com/.well-known/oauth-authorization-server/mcp`