OAuth 2.0 Guide

This guide explains how to integrate with Telerivet using OAuth 2.0, which allows your application to act on behalf of users. When a user authorizes your app, it receives an access token scoped to that user's permissions.

If your application only needs to access your own data with a fixed API key, see API Key authentication instead.

Setting Up an OAuth Client

Go to the Developer API settings page for your organization.
Click Add API Client and choose OAuth.
Enter a name for your application.
Choose the client type:
- Confidential – For server-side applications that can securely store a client secret.
- Public – For single-page apps, mobile apps, or CLI tools that cannot securely store a secret. Public clients must use PKCE (Proof Key for Code Exchange).
Enter one or more redirect URIs where users will be sent after authorization. (Not required for the Device Authorization flow.)
Optionally restrict the allowed scopes for this client.

After creating the client, you will receive a Client ID and (for confidential clients) a Client Secret. Store the client secret securely — it cannot be viewed again.

Client Availability

Each OAuth client has an availability setting that controls which users can authorize it:

Internal (default) – Only users who are members of the same organization that owns the OAuth client can authorize it. When an internal client initiates an authorization flow, the organization is automatically selected and the user cannot choose a different one. Even if a user has access to multiple organizations, the token will only be able to access data from the organization that owns the OAuth client.
External – Any Telerivet user can authorize the client, regardless of which organization they belong to. The user will be able to select which of their organizations to grant access to, or grant access to all of their organizations.

New OAuth clients are internal by default. This prevents an OAuth client from being used to send authorization requests to users outside your organization.

If your application needs to be authorized by users outside your organization, contact support to request external availability for your client. Once a client is made external, its name cannot be changed.

Scopes

Scopes control what an access token is allowed to do. When requesting authorization, your application specifies the scopes it needs as a space-separated string in the scope parameter.

Scope	Description
`projects:read`	Read project information and settings
`projects:write`	Create and modify projects and settings
`messages:read`	Read messages
`messages:delete`	Delete messages
`messages:send`	Send messages
`contacts:read`	Read contacts
`contacts:write`	Create and modify contacts
`routes:read`	Read routes and phone information
`routes:write`	Create and modify routes
`services:read`	Read services and automation rules
`services:write`	Create and modify services
`data:read`	Read data tables
`data:write`	Create and modify data tables
`billing:read`	Read billing and usage information
`stats:read`	Read project statistics
`airtime:read`	Read airtime transactions
`account:read`	Read organization information
`account:write`	Modify organization settings
`offline_access`	Maintain access when you are not using the application

Authorization Code Grant

The Authorization Code grant is the standard OAuth 2.0 flow for web and mobile applications. It redirects the user to Telerivet to log in and authorize your app, then redirects back with an authorization code that you exchange for tokens.

Step 1: Redirect the user to authorize

Redirect the user's browser to the authorization endpoint:

https://telerivet.com/oauth/authorize?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=REQUESTED_SCOPES
  &state=RANDOM_STATE_VALUE

Parameter	Required	Description
`response_type`	Yes	Must be `code`.
`client_id`	Yes	Your application's client ID.
`redirect_uri`	Yes	Must match one of the redirect URIs registered for your client.
`scope`	No	Space-separated list of scopes. Include `offline_access` to receive a refresh token.
`state`	Recommended	An opaque value to prevent CSRF attacks. Returned unchanged in the redirect.
`code_challenge`	Required for public clients	PKCE code challenge. See PKCE.
`code_challenge_method`	No	`S256` (recommended) or `plain`. Defaults to `plain`.

The user will be asked to log in (if not already logged in) and approve the requested scopes. They will also select which organization to grant access to.

Step 2: Receive the authorization code

After the user approves, they are redirected to your redirect_uri with an authorization code:

https://your-app.example.com/callback?
  code=AUTHORIZATION_CODE
  &state=RANDOM_STATE_VALUE

Verify that state matches the value you sent in Step 1.

Step 3: Exchange the code for tokens

Make a POST request to the token endpoint to exchange the authorization code for an access token:

POST https://api.telerivet.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=YOUR_REDIRECT_URI
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

For public clients, omit client_secret and include code_verifier instead. See PKCE.

The response includes an access token and (if offline_access scope was requested) a refresh token:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "projects:read messages:send offline_access"
}

PKCE (Proof Key for Code Exchange)

PKCE prevents authorization code interception attacks. It is required for public clients and recommended for all clients.

Generate a random code_verifier string (43–128 characters, using [A-Za-z0-9-._~]).
Compute the code_challenge as BASE64URL(SHA256(code_verifier)).
Include code_challenge and code_challenge_method=S256 in the authorization request (Step 1).
Include code_verifier in the token request (Step 3).

Device Authorization Grant

The Device Authorization Grant is designed for devices that have limited input capabilities (e.g., CLI tools, smart devices) or no browser. The user authorizes the device on a separate device with a browser.

Step 1: Request device authorization

Your application requests a device code from the device authorization endpoint:

POST https://api.telerivet.com/oauth/device_authorization
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_CLIENT_ID
&scope=REQUESTED_SCOPES

Response:

{
  "device_code": "DEVICE_CODE",
  "user_code": "ABCD-1234",
  "verification_uri": "https://telerivet.com/device",
  "verification_uri_complete": "https://telerivet.com/device?user_code=ABCD-1234",
  "expires_in": 1800,
  "interval": 5
}

Step 2: Display instructions to the user

Show the user the verification_uri and user_code. Instruct them to visit the URL in their browser and enter the code. Alternatively, provide the verification_uri_complete as a link or QR code.

Step 3: Poll for authorization

While the user authorizes on their browser, your application polls the token endpoint at the specified interval (in seconds):

POST https://api.telerivet.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=DEVICE_CODE
&client_id=YOUR_CLIENT_ID

While the user has not yet authorized, the response will be:

{
  "error": "authorization_pending",
  "error_description": "Authorization pending. Continue polling."
}

If you poll too frequently, you will receive a slow_down error. Increase your polling interval by 5 seconds and retry.

Once the user approves, the response includes an access token (same format as the Authorization Code grant).

Using Access Tokens

Include the access token in the Authorization header when making API requests:

GET https://api.telerivet.com/v1/projects
Authorization: Bearer YOUR_ACCESS_TOKEN

Access tokens expire after 1 hour. If you received a refresh token, use it to get a new access token without requiring the user to re-authorize.

Refreshing Access Tokens

To receive a refresh token, include offline_access in the requested scopes. When the access token expires, exchange the refresh token for a new one:

POST https://api.telerivet.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Response:

{
  "access_token": "NEW_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "projects:read messages:send offline_access"
}

The refresh token may also be rotated, so always store the latest refresh token from the response.

Revoking Tokens

To revoke an access token or refresh token (e.g., when a user disconnects your application):

POST https://api.telerivet.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=TOKEN_TO_REVOKE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

This endpoint always returns HTTP 200, per RFC 7009. You can optionally include token_type_hint (access_token or refresh_token) to help the server identify the token type.

Users can also revoke access from their Account Security settings page.

Error Handling

Token endpoint errors return a JSON response with error and error_description fields:

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired"
}

Common error codes:

Error Code	Description
`invalid_request`	A required parameter is missing or invalid.
`invalid_client`	Client authentication failed (invalid client_id or client_secret).
`invalid_grant`	The authorization code or refresh token is invalid, expired, or already used.
`invalid_scope`	The requested scope is not allowed for this client.
`unsupported_grant_type`	The grant_type is not supported.
`authorization_pending`	Device flow: the user has not yet authorized the device.
`slow_down`	Device flow: the client is polling too frequently.
`expired_token`	Device flow: the device code has expired.
`access_denied`	The user denied the authorization request.

Endpoint Reference

Endpoint	Method	URL
Authorization	GET	`https://telerivet.com/oauth/authorize`
Token	POST	`https://api.telerivet.com/oauth/token`
Device Authorization	POST	`https://api.telerivet.com/oauth/device_authorization`
Token Revocation	POST	`https://api.telerivet.com/oauth/revoke`
Device Verification	GET	`https://telerivet.com/device`