API reference

OAuth 2.0

Build third-party apps that access JagCall on behalf of your users with the standard authorization code flow.

Overview

JagCall implements the OAuth 2.0 Authorization Code flow, the industry standard for third-party integrations. Your application requests specific permissions from a JagCall user, who approves access through a consent screen, and 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.

Authorization code flow

1
Register an OAuth client
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.
Store your client secret securely
The client_secret is shown only once and cannot be retrieved later.

2

Redirect to the authorization URL

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

url

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

3
User approves consent
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:
redirect
https://yourapp.com/callback?code=jc_auth_code_xxx&state=random_csrf_token
Verify state
Always confirm the state parameter matches the value you sent to prevent CSRF attacks. The authorization code expires in 10 minutes.

4

Exchange the code for tokens

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

curl

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"  }'

response

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

5
Use the access token
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
curl -X GET https://jagcall.com/v1/agents \ -H "Authorization: Bearer jca_xxx..." \ -H "Content-Type: application/json"

6

Refresh the token

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

curl

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"  }'

response

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

Available scopes

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

Scope	Description
`agents:read`	List and view agent details
`agents:write`	Create, update, and delete agents
`calls:read`	List calls, transcripts, and recordings
`calls:write`	Initiate outbound calls
`phone-numbers:read`	List and view phone numbers
`phone-numbers:write`	Purchase, update, and release numbers
`sms:read`	List SMS conversations and messages
`sms:write`	Send SMS messages
`contacts:read`	List and view contacts
`contacts:write`	Create and update contacts
`campaigns:read`	List campaigns and their contacts
`campaigns:write`	Create, edit, and run outbound campaigns
`calendar:read`	View calendar integrations and availability
`calendar:write`	Book appointments on connected calendars
`analytics:read`	View analytics and reports
`billing:read`	View account balance and usage
`webhooks:read`	List webhook configurations
`webhooks:write`	Create and update webhook endpoints

Token format reference

Token type	Prefix	Expiration
API key	`jc_live_`	No expiry by default
OAuth access token	`jca_`	1 hour
OAuth refresh token	`jcr_`	30 days (rolling)

Still need help?

Can't find what you're looking for? Send us a message and our team will get back to you.

Contact support