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	Opaque, prefixed `rkoa_`
Refresh token	7 days	Opaque, prefixed `rkor_`. Use to obtain new access tokens.

Access tokens are sent via the Authorization header:

Authorization: Bearer rkoa_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"],
  },
  baseUrl: "https://api.revkeen.com",
});

const customers = await client.customers.list({ limit: 10 });

Pass OAuth client credentials on RevKeenClient's oauth option. The SDK acquires and refreshes tokens; see the flows below.

Go

client, err := revkeen.NewClient(
    os.Getenv("REVKEEN_API_KEY"),
    revkeen.EnvironmentProduction,
)
if err != nil {
    log.Fatal(err)
}

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.

A token that is expired or no longer valid returns 401 with type: authentication_error and code: session_invalid. A valid token missing a required scope returns 403 with type: authorization_error and code: insufficient_permissions. See Errors.

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`