Getting started

Every OmaxTelecom API works the same way: you sign in with your Client ID and Client Secret, get a short-lived access token, and send that token with each request. This page takes you from zero to your first API call in a few minutes.

1. Get your credentials

Sign in to OmaxTelecom Console, or create an account.
Open the API settings and copy your Client ID and Client Secret.
Make sure the API you want to use is enabled for your organization. If it is not, contact support@omaxtelecom.com.

[!WARNING] The Client Secret is like a password. Use it only on your server — never in a website, mobile app or public repository.

2. Get an access token

Send your credentials to the token endpoint. The body is form-encoded (application/x-www-form-urlencoded), not JSON.

curl -X POST https://api.omaxtelecom.com/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "openid"
}

The token is valid for expires_in seconds (usually 5 minutes). The same token works for every OmaxTelecom API.

3. Make your first call

Send the token in the Authorization header. This call checks your token and organization on the SMS API:

curl https://api.omaxtelecom.com/sms/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

That's it — every other request works the same way.

4. Choose your API

If you want to…	Use
Send SMS and get delivery reports	SMS API
Verify a phone number with a one-time code	OTP API
Sell eSIM / SIM data plans to your customers	Bappy API
Manage your own SIM inventory, coverages and plans	Telkor API
Check that a phone number is valid	Phone Validation API
Find the carrier of a phone number	Number Lookup API
Look up a mobile operator by MCC/MNC	MCC-MNC API
Buy phone numbers and route calls and SMS	Phone Numbers API

Try it without writing code

In this portal — on any API page, enter your Client ID and Client Secret in the Authentication box and click Authorize. Then open an endpoint and click Test Request.
In Postman — every API page has a Postman collection and environment to download. Fill in client_id and client_secret in the environment.

Reuse the token in your code

Don't request a new token before every call. Keep the token in memory and get a new one shortly before it expires, or when an API answers 401 Unauthorized.

Node.js

const TOKEN_URL = "https://api.omaxtelecom.com/auth/token";
let cached = null; // { token, expiresAt }

export async function getToken() {
  // Refresh 30 seconds early so a token never expires mid-request.
  if (cached && Date.now() < cached.expiresAt - 30_000) return cached.token;

  const response = await fetch(TOKEN_URL, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: process.env.OMAX_CLIENT_ID,
      client_secret: process.env.OMAX_CLIENT_SECRET,
    }),
  });
  if (!response.ok) throw new Error(`Token request failed: ${response.status}`);

  const data = await response.json();
  cached = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

// Usage
const res = await fetch("https://api.omaxtelecom.com/sms/me", {
  headers: { Authorization: `Bearer ${await getToken()}` },
});

Python

import os, time, requests

TOKEN_URL = "https://api.omaxtelecom.com/auth/token"
_cached = {"token": None, "expires_at": 0}

def get_token():
    # Refresh 30 seconds early so a token never expires mid-request.
    if _cached["token"] and time.time() < _cached["expires_at"] - 30:
        return _cached["token"]

    response = requests.post(TOKEN_URL, data={
        "grant_type": "client_credentials",
        "client_id": os.environ["OMAX_CLIENT_ID"],
        "client_secret": os.environ["OMAX_CLIENT_SECRET"],
    })
    response.raise_for_status()
    data = response.json()
    _cached.update(token=data["access_token"], expires_at=time.time() + data["expires_in"])
    return _cached["token"]

# Usage
me = requests.get("https://api.omaxtelecom.com/sms/me",
                  headers={"Authorization": f"Bearer {get_token()}"})

Token errors

Status	`error`	What it means	What to do
`400`	`invalid_request`	`grant_type` is missing, or the body was sent as JSON	Send a form-encoded body with `grant_type=client_credentials`
`401`	`invalid_client`	Wrong Client ID or Client Secret	Copy both again from Console; check for extra spaces
`401` from an API	—	The access token expired or is missing	Get a new token and retry once

Keep your credentials safe

Call the token endpoint from your server only. Never put the Client Secret in a website, mobile app or public repository.
Store the Client ID and Client Secret in environment variables or a secrets manager.
If a secret leaks, replace it in Console right away, or contact support@omaxtelecom.com.

Need help?

Email support@omaxtelecom.com. Tell us which endpoint you called, when, and what the response was — including its request_id if it has one. Never send your Client Secret or access token.