Integrating with Existing OAuth - ATH Developer Guide

You Already Have OAuth. Now What?

If you use Auth0, Clerk, Firebase Auth, or your own OAuth server, you don’t need to build a new one. You just point ATH’s config at your existing endpoints.

The One Config Change

In your createATHHandlers config, the oauth section tells ATH where to send users for consent:

const handlers = createATHHandlers({
  // ... other config ...
  config: {
    // ...
    oauth: {
      authorize_endpoint: "https://your-auth-provider.com/authorize",
      token_endpoint: "https://your-auth-provider.com/oauth/token",
      client_id: "your-ath-client-id",      // registered with your OAuth provider
      client_secret: "your-ath-client-secret",
    },
  },
});

What ATH Does With Your OAuth

In short:

ATH builds a redirect URL to your OAuth authorize endpoint (with PKCE)
Your OAuth server shows the consent screen to the user
After consent, your OAuth server redirects to /ath/callback with an authorization code
ATH exchanges that code at your token endpoint (server-side, with PKCE verifier)
ATH stores the resulting token internally — the agent never sees it

Setup Per Provider

Auth0
Clerk
Custom OAuth

Create a “Regular Web Application” in Auth0 dashboard
Set Allowed Callback URL to https://your-app.com/ath/callback
Note the Client ID and Client Secret
Use these in your ATH config:

oauth: {
  authorize_endpoint: "https://YOUR_DOMAIN.auth0.com/authorize",
  token_endpoint: "https://YOUR_DOMAIN.auth0.com/oauth/token",
  client_id: "YOUR_AUTH0_CLIENT_ID",
  client_secret: "YOUR_AUTH0_CLIENT_SECRET",
}

In Clerk dashboard, go to JWT Templates or use the OAuth endpoints
Set redirect URL to https://your-app.com/ath/callback
Configure:

oauth: {
  authorize_endpoint: "https://YOUR_CLERK_DOMAIN/oauth/authorize",
  token_endpoint: "https://YOUR_CLERK_DOMAIN/oauth/token",
  client_id: "YOUR_CLERK_CLIENT_ID",
  client_secret: "YOUR_CLERK_CLIENT_SECRET",
}

If you built your own OAuth server (like the demo does):

oauth: {
  authorize_endpoint: "https://your-app.com/oauth/authorize",
  token_endpoint: "https://your-app.com/oauth/token",
  client_id: "ath-internal-client",
  client_secret: "ath-internal-secret",
}

Make sure your OAuth server:

Supports Authorization Code grant with PKCE (S256)
Has https://your-app.com/ath/callback in allowed redirect URIs

Requirements for Your OAuth Server

ATH needs your OAuth server to support:

Feature	Required?	Why
Authorization Code grant	✅	Core flow
PKCE (S256)	✅	Security — prevents code interception
Custom scopes	Recommended	So users see meaningful permissions on consent screen
Token endpoint returns JSON	✅	ATH parses the response

Most modern OAuth providers (Auth0, Clerk, Keycloak, etc.) support all of these out of the box.

What if My OAuth Doesn’t Support PKCE?

Older OAuth servers might not support PKCE. In that case, you have two options:

Upgrade your OAuth server — most have PKCE support as a toggle
Use the ATH Gateway instead — put a gateway in front of your service, and the gateway handles PKCE with its own OAuth client. See Set Up a Gateway.

Server-Side Tutorial

​You Already Have OAuth. Now What?

​The One Config Change

​What ATH Does With Your OAuth

​Setup Per Provider

​Requirements for Your OAuth Server