Authentication

The Phonovation SMS API v2 uses OAuth 2.0 password grant to issue short-lived JWT access tokens. Every API request must include a valid token in the Authorization header.

Step 1: Obtain a token

Send a POST request to the auth server with your credentials:

curl -X POST https://auth.interactsms.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&client_id=ismstoken&username=YOUR_USERNAME&password=YOUR_PASSWORD"

import requests

res = requests.post(
    "https://auth.interactsms.com/token",
    data={
        "grant_type": "password",
        "client_id": "ismstoken",
        "username": "YOUR_USERNAME",
        "password": "YOUR_PASSWORD"
    }
)

print(res.json())

using System.Net.Http;

using var client = new HttpClient();

var body = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "password",
    ["client_id"] = "ismstoken",
    ["username"] = "YOUR_USERNAME",
    ["password"] = "YOUR_PASSWORD"
});

var res = await client.PostAsync("https://auth.interactsms.com/token", body);
Console.WriteLine(await res.Content.ReadAsStringAsync());

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

String form = "grant_type=password"
    + "&client_id=ismstoken"
    + "&username=" + URLEncoder.encode("YOUR_USERNAME", StandardCharsets.UTF_8)
    + "&password=" + URLEncoder.encode("YOUR_PASSWORD", StandardCharsets.UTF_8);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://auth.interactsms.com/token"))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .POST(HttpRequest.BodyPublishers.ofString(form))
    .build();

HttpResponse<String> res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

$client = new GuzzleHttp\Client();

$res = $client->post('https://auth.interactsms.com/token', [
    'form_params' => [
        'grant_type' => 'password',
        'client_id' => 'ismstoken',
        'username' => 'YOUR_USERNAME',
        'password' => 'YOUR_PASSWORD',
    ],
]);

echo $res->getBody();

const res = await fetch("https://auth.interactsms.com/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "password",
    client_id: "ismstoken",
    username: "YOUR_USERNAME",
    password: "YOUR_PASSWORD",
  }),
});

console.log(await res.json());

Successful response:

Token response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 120,
  "refresh_expires_in": 1200,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "scope": "email profile client_id"
}

Access tokens expire after 120 seconds. Refresh tokens expire after 1200 seconds. Build token refresh logic into your integration.

Step 2: Use the token

Pass the access_token as a Bearer token in all API requests:

curl https://api.interactsms.com/api/v2/senderlist \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

import requests

res = requests.get(
    "https://api.interactsms.com/api/v2/senderlist",
    headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
)

print(res.json())

using System.Net.Http.Headers;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_ACCESS_TOKEN");

var res = await client.GetAsync("https://api.interactsms.com/api/v2/senderlist");

Console.WriteLine(await res.Content.ReadAsStringAsync());

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.interactsms.com/api/v2/senderlist"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .GET()
    .build();

HttpResponse<String> res = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

$client = new GuzzleHttp\Client();

$res = $client->get('https://api.interactsms.com/api/v2/senderlist', [
    'headers' => ['Authorization' => 'Bearer YOUR_ACCESS_TOKEN'],
]);

echo $res->getBody();

const res = await fetch("https://api.interactsms.com/api/v2/senderlist", {
  headers: {
    Authorization: "Bearer YOUR_ACCESS_TOKEN",
  },
});

console.log(await res.json());

Token expiry & refresh strategy

Token	Expiry
`access_token`	120 seconds
`refresh_token`	1200 seconds

Because tokens are short-lived, the recommended approach is to re-authenticate before each request or implement proactive refresh. The safest pattern is to catch a 401 Unauthorized response and immediately re-authenticate with your credentials before retrying the request.

ACCESS_TOKEN=$(
  curl -s -X POST https://auth.interactsms.com/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=password&client_id=ismstoken&username=$ISMSAPI_USERNAME&password=$ISMSAPI_PASSWORD" \
  | jq -r '.access_token'
)

curl https://api.interactsms.com/api/v2/senderlist \
  -H "Authorization: Bearer $ACCESS_TOKEN"

async function getToken() {
  const res = await fetch('https://auth.interactsms.com/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'password',
      client_id: 'ismstoken',
      username: process.env.ISMSAPI_USERNAME,
      password: process.env.ISMSAPI_PASSWORD
    })
  });
  const { access_token } = await res.json();
  return access_token;
}

async function apiRequest(path, options = {}) {
  const token = await getToken();
  const res = await fetch(`https://api.interactsms.com${path}`, {
    ...options,
    headers: {
      ...options.headers,
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });
  if (res.status === 401) throw new Error('Authentication failed');
  return res.json();
}

import os, requests

def get_token():
    res = requests.post(
        'https://auth.interactsms.com/token',
        data={
            'grant_type': 'password',
            'client_id': 'ismstoken',
            'username': os.environ['ISMSAPI_USERNAME'],
            'password': os.environ['ISMSAPI_PASSWORD']
        }
    )
    return res.json()['access_token']

def api_request(path, **kwargs):
    token = get_token()
    res = requests.request(
        url=f'https://api.interactsms.com{path}',
        headers={'Authorization': f'Bearer {token}'},
        **kwargs
    )
    res.raise_for_status()
    return res.json()

using System.Net.Http.Headers;
using System.Text.Json;

using var client = new HttpClient();

async Task<string> GetToken()
{
    var body = new FormUrlEncodedContent(new Dictionary<string, string>
    {
        ["grant_type"] = "password",
        ["client_id"] = "ismstoken",
        ["username"] = Environment.GetEnvironmentVariable("ISMSAPI_USERNAME")!,
        ["password"] = Environment.GetEnvironmentVariable("ISMSAPI_PASSWORD")!
    });

    var res = await client.PostAsync("https://auth.interactsms.com/token", body);
    var json = JsonDocument.Parse(await res.Content.ReadAsStringAsync());
    return json.RootElement.GetProperty("access_token").GetString()!;
}

async Task<string> ApiRequest(string path)
{
    var token = await GetToken();
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);

    var res = await client.GetAsync($"https://api.interactsms.com{path}");
    if ((int)res.StatusCode == 401) throw new Exception("Authentication failed");
    return await res.Content.ReadAsStringAsync();
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

HttpClient client = HttpClient.newHttpClient();

String getToken() throws Exception {
    String form = "grant_type=password"
        + "&client_id=ismstoken"
        + "&username=" + URLEncoder.encode(System.getenv("ISMSAPI_USERNAME"), StandardCharsets.UTF_8)
        + "&password=" + URLEncoder.encode(System.getenv("ISMSAPI_PASSWORD"), StandardCharsets.UTF_8);

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://auth.interactsms.com/token"))
        .header("Content-Type", "application/x-www-form-urlencoded")
        .POST(HttpRequest.BodyPublishers.ofString(form))
        .build();

    HttpResponse<String> res = client.send(request, HttpResponse.BodyHandlers.ofString());
    return res.body().split("\"access_token\":\"")[1].split("\"")[0];
}

String apiRequest(String path) throws Exception {
    String token = getToken();
    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.interactsms.com" + path))
        .header("Authorization", "Bearer " + token)
        .GET()
        .build();

    HttpResponse<String> res = client.send(request, HttpResponse.BodyHandlers.ofString());
    if (res.statusCode() == 401) throw new RuntimeException("Authentication failed");
    return res.body();
}

$client = new GuzzleHttp\Client();

function getToken($client) {
    $res = $client->post('https://auth.interactsms.com/token', [
        'form_params' => [
            'grant_type' => 'password',
            'client_id' => 'ismstoken',
            'username' => getenv('ISMSAPI_USERNAME'),
            'password' => getenv('ISMSAPI_PASSWORD'),
        ],
    ]);

    return json_decode($res->getBody(), true)['access_token'];
}

function apiRequest($client, $path) {
    $token = getToken($client);
    $res = $client->get('https://api.interactsms.com' . $path, [
        'headers' => ['Authorization' => 'Bearer ' . $token],
    ]);

    return json_decode($res->getBody(), true);
}

Never hardcode credentials in your source code. Use environment variables or a secrets manager.

No sandbox environment

There is currently no sandbox or test environment. All API calls run against the live production system and will consume message credits. Test with a small number of your own numbers to verify your integration before going live.

Credentials

Your username and password are available from your Phonovation account. Contact support@phonovation.com if you need access.

Get started

Send messages

Receive events

Security and compliance

Tools

Step 1: Obtain a token

Step 2: Use the token

Token expiry & refresh strategy

No sandbox environment

Credentials

​Step 1: Obtain a token

​Step 2: Use the token

​Token expiry & refresh strategy

​No sandbox environment

​Credentials

Step 1: Obtain a token

Step 2: Use the token

Token expiry & refresh strategy

No sandbox environment

Credentials