OAuth 2.0

Before you can authenticate users, register your application as an OAuth client:

1. Open Settings → General → OAuth Applications (requires superadmin role).
2. Click Register App.
3. Enter your application name and redirect URI.
4. Copy the client_id and client_secret.

Each app has a scope allowlist; a request can only be granted scopes on that list. MCP clients such as Claude can instead self-register with dynamic client registration (POST /api/oauth/register, RFC 7591), and public clients (token_endpoint_auth_method: none) have no secret and must use PKCE. Server metadata is published at /.well-known/oauth-authorization-server.

Direct the user to the JagCall authorization endpoint with your client ID, redirect URI, requested scopes, and a CSRF state parameter. Add a PKCE challenge (S256 only; plain is rejected) — it is required for public clients and recommended for all:

https://jagcall.com/oauth/authorize?  response_type=code  &client_id=YOUR_CLIENT_ID  &redirect_uri=https://yourapp.com/callback  &scope=agents:read calls:read calls:write  &state=random_csrf_token  &code_challenge=BASE64URL_SHA256_OF_VERIFIER  &code_challenge_method=S256

The redirect_uri must exactly match a registered URI. The one exception is a loopback http:// URI (127.0.0.1, localhost, [::1]), where the port may vary.

JagCall displays a consent screen showing your application name and the requested scopes. When the user approves, JagCall redirects back to your redirect_uri with an authorization code:

https://yourapp.com/callback?code=jc_auth_code_xxx&state=random_csrf_token

Exchange the authorization code for an access token and refresh token. Send code_verifier if you sent a code_challenge; public clients omit client_secret. The token endpoint accepts JSON, form-encoded bodies, or HTTP Basic client authentication, and is limited to 30 requests per minute.

curl -X POST https://jagcall.com/api/oauth/token \  -H "Content-Type: application/json" \  -d '{    "grant_type": "authorization_code",    "code": "AUTH_CODE_FROM_REDIRECT",    "client_id": "YOUR_CLIENT_ID",    "client_secret": "YOUR_CLIENT_SECRET",    "redirect_uri": "https://yourapp.com/callback",    "code_verifier": "YOUR_PKCE_CODE_VERIFIER"  }'

{  "access_token": "jca_xxx...",  "token_type": "Bearer",  "expires_in": 3600,  "refresh_token": "jcr_xxx...",  "scope": "agents:read calls:read calls:write"}

Include the access token as a Bearer token in API requests, just like an API key. Access tokens use the jca_ prefix and expire after 1 hour. They are limited to the granted scopes, act on the organization the user chose on the consent screen, and are subject to the same rate limits as API keys.

curl -X GET https://jagcall.com/v1/agents \  -H "Authorization: Bearer jca_xxx..."  \  -H "Content-Type: application/json"

When the access token expires, use the refresh token (prefix jcr_) to obtain a new one without user interaction:

curl -X POST https://jagcall.com/api/oauth/token \  -H "Content-Type: application/json" \  -d '{    "grant_type": "refresh_token",    "refresh_token": "jcr_xxx...",    "client_id": "YOUR_CLIENT_ID",    "client_secret": "YOUR_CLIENT_SECRET"  }'

{  "access_token": "jca_new_xxx...",  "token_type": "Bearer",  "expires_in": 3600,  "refresh_token": "jcr_new_xxx...",  "scope": "agents:read calls:read calls:write"}

Revoke an access or refresh token when the user disconnects your integration:

curl -X POST https://jagcall.com/api/oauth/revoke \  -H "Content-Type: application/json" \  -d '{    "token": "jcr_xxx...",    "client_id": "YOUR_CLIENT_ID",    "client_secret": "YOUR_CLIENT_SECRET"  }'