OAuth 2.0 Integration

Overview

JagCall implements the OAuth 2.0 Authorization Code flow, the industry standard for third-party integrations. This allows your application to request specific permissions from a JagCall user, who approves access through a consent screen. Your app then exchanges the authorization code for access and refresh tokens.

OAuth is ideal when your application acts on behalf of another JagCall user. For server-to-server access to your own account, use API keys instead.

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

1. Navigate to Settings → OAuth Clients (requires superadmin role).
2. Click Create OAuth Client.
3. Enter your application name and one or more redirect URIs.
4. Copy the client_id and client_secret.

Direct the user to the JagCall authorization endpoint with your client ID, redirect URI, requested scopes, and a CSRF state parameter:

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

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

Always verify the state parameter matches the value you sent to prevent CSRF attacks. The authorization code expires in 10 minutes.

Exchange the authorization code for an access token and refresh token:

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

{
  "access_token": "jca_xxx...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "jc_refresh_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.

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 jc_refresh_) to obtain a new one without user interaction:

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

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

Refresh tokens are single-use. Each refresh response includes a new refresh token that must be stored for the next refresh cycle. Refresh tokens expire after 30 days of inactivity.

Request only the scopes your application needs. Users see the full list of requested permissions on the consent screen.

Token Format Reference