OAuth 2.0 Authentication

What is OAuth 2.0?

OAuth 2.0 is an industry-standard way for an application to prove who it is without sending a long-lived password on every request. Instead of your gateway application name and password, your application uses an OAuth client: a client ID and client secret that it exchanges for a short-lived access token.

We use the OAuth 2.0 Client Credentials grant (RFC 6749 section 4.4), which is designed for server-to-server integrations where no end user is present.

Benefits

  • Short-lived credentials on the wire. Access tokens expire after a few minutes, so a leaked token is only useful for a short time.
  • Least privilege. Each OAuth client is granted only the permissions (scopes) it needs, for example send-only.
  • Independent credentials per system. Create a separate OAuth client for each system or environment, and deactivate one without affecting the others.

Which APIs support OAuth 2.0?

Each API’s documentation says whether it supports OAuth 2.0 in its Authentication section, along with the scopes it uses and the errors it returns. Where an API supports OAuth 2.0, your existing authentication continues to work, so you can move to OAuth 2.0 at your own pace.

How it works

  1. Create an OAuth client for one of your gateway applications and choose the permissions (scopes) it needs. You receive a client ID and a client secret.
  2. Request an access token. Your application sends the client ID and secret to the token URL, in an HTTP Basic Authorization header or in the request body, and receives an access token.
  3. Call the API. Your application sends the access token in the Authorization: Bearer header on each API request.
  4. Reuse the token until it expires, then request a new one with the same client ID and secret.

An access token acts as the gateway application it belongs to. Messages you send with it use that application’s sender IDs, routing, callbacks, IP allowlist and billing, exactly as they do with your application name and password.

Key concepts

Term Description
OAuth client A set of credentials linked to one of your gateway applications. An application can have several OAuth clients.
Client ID The public identifier of an OAuth client: a 32-character string of lowercase letters and digits.
Client secret The private password for an OAuth client. It is shown once, when the client is created.
Access token A short-lived token returned by the token URL. Send it as Authorization: Bearer <access_token>.
Scope A permission granted to an OAuth client, written as <api>/<permission>, for example sms.restv2/message.send. Each API lists its scopes in its Authentication section.
Token URL The endpoint that issues access tokens: https://api.modicagroup.com/oauth2/token

An OAuth client only works with the API its application belongs to. A token issued for one API is rejected by the others.

Getting OAuth credentials

You create OAuth clients for an application in omni.modicagroup.com, on that application’s API Configuration page. Each API’s Authentication section has the exact steps.

When you create an OAuth client:

  • Give it a name that identifies where it is used, for example Billing system - production.
  • Select only the permissions that system needs.
  • Copy the Client ID and Client Secret and store them securely, for example in your secrets manager.
warningThe client secret is shown only once. It can’t be retrieved later. If you lose it, create a new OAuth client and revoke the old one.

Requesting an access token

Send a POST request to the token URL with an application/x-www-form-urlencoded body, and authenticate with your client ID and secret.

Client authentication methods

The token URL supports both client authentication methods in the OAuth 2.0 standard (RFC 6749 section 2.3.1). Use whichever your HTTP client or OAuth library supports.

Method How to send the credentials OAuth name
HTTP Basic (recommended by the standard) In the Authorization header: Basic followed by the Base64 encoding of <client_id>:<client_secret> client_secret_basic
Request body As the client_id and client_secret form parameters client_secret_post

Use exactly one method in each request. A request that sends the client secret in both the Authorization header and the body is rejected with invalid_request.

Most HTTP clients and OAuth libraries build the HTTP Basic header for you, for example cURL’s --user option. The standard says to URL-encode the client ID and secret before Base64-encoding them. Our client IDs and secrets contain only letters, digits, - and _, which URL encoding doesn’t change, so libraries that skip this step work too.

Send the Authorization header with your first request. The token URL doesn’t send an authentication challenge for your client to answer, so an HTTP client that only sends credentials after a challenge never authenticates. Turn on pre-emptive authentication in such a client (for example PreAuthenticate in .NET), or set the Authorization header yourself.

Using HTTP Basic:

POST https://api.modicagroup.com/oauth2/token
Authorization: Basic <base64 of client_id:client_secret>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=<scope>

Using the request body:

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

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>&scope=<scope>

Request parameters

Parameter Required Description
grant_type Yes Must be client_credentials.
client_id Request body method only Your OAuth client ID. With HTTP Basic, leave it out, or send the same client ID as in the header.
client_secret Request body method only Your OAuth client secret. Never send it in the body when you use HTTP Basic.
scope No A space-separated list of scopes. Leave it out to receive every scope granted to the client. Every scope you request must have been granted to the client.

Token response

On success:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Ii4uLiIsInR5cCI6ImF0K2p3dCJ9.eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "sms.restv2/message.send"
}
Field Description
access_token The token to send on API requests. Treat it as opaque, and don’t rely on its contents.
token_type Always Bearer.
expires_in The number of seconds until the token expires.
scope The scopes granted to this token.

No refresh token is issued. When a token is about to expire, request a new one with your client credentials.

Token URL errors

Errors from the token URL use the standard OAuth 2.0 error format:

{
  "error": "invalid_client",
  "error_description": "Authentication failed"
}
HTTP status error Meaning and what to do
400 invalid_request A required parameter is missing or badly formatted, or the request uses both client authentication methods. Check that the body is form-encoded, and that the credentials are either in the Authorization header or in the body, not both.
400 unsupported_grant_type grant_type must be client_credentials.
400 invalid_scope You requested a scope that hasn’t been granted to this client, or the scope is badly formatted. Remove scope to receive every granted scope.
401 invalid_client The client ID or secret is wrong, the client is deactivated or revoked, or the Authorization header isn’t valid HTTP Basic.
429 too_many_requests Too many token requests for this client. Reuse tokens until they expire, and wait before retrying.
500 server_error Something went wrong on our side. Retry with a backoff. If it continues, contact support.

For security reasons, invalid_client doesn’t say which part of the credentials was wrong.

Example: sending an SMS with REST v2

This example shows the whole flow with REST v2, using an OAuth client that has the sms.restv2/message.send scope.

1. Request an access token

Using HTTP Basic:

curl -X POST \
  --user 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=sms.restv2/message.send' \
  https://api.modicagroup.com/oauth2/token
const credentials = Buffer.from(
  `${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`
).toString("base64");

const response = await fetch("https://api.modicagroup.com/oauth2/token", {
  method: "POST",
  headers: {
    "Authorization": `Basic ${credentials}`,
    "Content-Type": "application/x-www-form-urlencoded"
  },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    scope: "sms.restv2/message.send"
  })
});

const token = await response.json();
// token.access_token, token.expires_in
import os
import requests

response = requests.post(
    "https://api.modicagroup.com/oauth2/token",
    auth=(os.environ["CLIENT_ID"], os.environ["CLIENT_SECRET"]),
    data={
        "grant_type": "client_credentials",
        "scope": "sms.restv2/message.send",
    },
    timeout=10,
)
response.raise_for_status()
token = response.json()
print(token["expires_in"])
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text;

using var client = new HttpClient();
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes(
    $"{Environment.GetEnvironmentVariable("CLIENT_ID")}:{Environment.GetEnvironmentVariable("CLIENT_SECRET")}"));
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.modicagroup.com/oauth2/token")
{
    Content = new FormUrlEncodedContent(new Dictionary<string, string>
    {
        ["grant_type"] = "client_credentials",
        ["scope"] = "sms.restv2/message.send"
    })
};
request.Headers.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
var token = await response.Content.ReadFromJsonAsync<Dictionary<string, object>>();

Using the request body:

curl -X POST \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'scope=sms.restv2/message.send' \
  https://api.modicagroup.com/oauth2/token
const response = await fetch("https://api.modicagroup.com/oauth2/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: process.env.CLIENT_ID,
    client_secret: process.env.CLIENT_SECRET,
    scope: "sms.restv2/message.send"
  })
});

const token = await response.json();
// token.access_token, token.expires_in
import os
import requests

response = requests.post(
    "https://api.modicagroup.com/oauth2/token",
    data={
        "grant_type": "client_credentials",
        "client_id": os.environ["CLIENT_ID"],
        "client_secret": os.environ["CLIENT_SECRET"],
        "scope": "sms.restv2/message.send",
    },
    timeout=10,
)
response.raise_for_status()
token = response.json()
print(token["expires_in"])
using System.Net.Http.Json;

using var client = new HttpClient();
var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "client_credentials",
    ["client_id"] = Environment.GetEnvironmentVariable("CLIENT_ID")!,
    ["client_secret"] = Environment.GetEnvironmentVariable("CLIENT_SECRET")!,
    ["scope"] = "sms.restv2/message.send"
});

var response = await client.PostAsync("https://api.modicagroup.com/oauth2/token", form);
response.EnsureSuccessStatusCode();
var token = await response.Content.ReadFromJsonAsync<Dictionary<string, object>>();

2. Send an SMS with the access token

Send the access token in the Authorization header. Everything else about the request is the same as with your application name and password.

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{"destination": "+64211234567", "content": "Hello world!"}' \
  https://api.modicagroup.com/rest/sms/v2/messages
const response = await fetch("https://api.modicagroup.com/rest/sms/v2/messages", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    destination: "+64211234567",
    content: "Hello world!"
  })
});

const result = await response.json();
import requests

access_token = "ACCESS_TOKEN_FROM_STEP_1"

response = requests.post(
    "https://api.modicagroup.com/rest/sms/v2/messages",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {access_token}",
    },
    json={"destination": "+64211234567", "content": "Hello world!"},
    timeout=10,
)

if response.status_code == 202:
    print(response.json())
else:
    print("Error:", response.status_code, response.text)
using System.Net.Http.Headers;
using System.Text;

using var client = new HttpClient();
var request = new HttpRequestMessage(
    HttpMethod.Post,
    "https://api.modicagroup.com/rest/sms/v2/messages");
request.Headers.Accept.ParseAdd("application/json");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
request.Content = new StringContent(
    """{"destination":"+64211234567","content":"Hello world!"}""",
    Encoding.UTF8,
    "application/json");

var response = await client.SendAsync(request);
var responseBody = await response.Content.ReadAsStringAsync();

On success, REST v2 returns 202 Accepted with the message UUID, as described in Sending messages.

Reuse tokens until they expire

Request a token once and reuse it for every API call until it is close to expiry. Don’t request a new token for every message. The token URL is rate limited per client, and requesting a token on each message adds latency to every send.

A reliable pattern is:

  1. Cache the access token together with the time it expires (now + expires_in).
  2. Before each API call, reuse the cached token if it has at least 60 seconds left. Otherwise, request a new one.
  3. If an API call rejects the token, request a new token once and retry the call. If it fails again, stop and investigate. Don’t retry in a loop. Each API’s Authentication section lists the errors it returns.

Managing OAuth clients

You can see your OAuth clients and change their status on the application’s API Configuration page.

Status Can request new tokens Can change to
Active Yes Deactivated, Revoked
Deactivated No Active, Revoked
Revoked No. This is permanent. None
  • Deactivate a client to pause it temporarily, for example while you investigate a suspected leak. You can activate it again later with the same client ID and secret.
  • Revoke a client when it is no longer needed or its secret may have been exposed. Revoking can’t be undone.

Replacing a client secret

To replace a secret without downtime:

  1. Create a new OAuth client with the same permissions.
  2. Update your systems to use the new client ID and secret.
  3. Confirm your systems are working with the new credentials.
  4. Revoke the old OAuth client.

Security recommendations

  • Store client secrets in a secrets manager or encrypted configuration. Never put them in source code, logs or client-side (browser or mobile) apps.
  • Create a separate OAuth client for each system and each environment, and give each one only the scopes it needs.
  • Treat access tokens as secrets. Don’t log them.
  • Always use HTTPS and verify our TLS certificate. See SSL Certificates.
  • Review your OAuth clients regularly, and revoke any that are no longer in use.
  • Once all your systems use OAuth 2.0, ask support@modicagroup.com about retiring the password for that application, so only OAuth credentials can be used.