API Authentication & Tokens

How authentication works

The Simple Telecom API uses Bearer token authentication. On every request you send your token in the Authorization header in the form:

Authorization: Bearer st_your_token_here

Tokens start with st_ so they're easy to recognise — and easy to spot if one leaks into logs.

A token is scoped to your account. It can read and manage your services, CDRs and routing. It cannot touch any other account's data. Requests to services that don't belong to the account that owns the token are rejected with a 403 unauthorized_service error.

Where tokens come from

Tokens are issued from the customer console:

1. Log in at console.simpletelecom.com.au/login.
2. Open Settings → API Access.
3. Click Generate API Token and copy it immediately — the full token is only shown once.

Security note: A blank token means API access is disabled for your account. If you believe a token has been compromised, revoke it immediately from the same screen and generate a replacement.

A quick authenticated request

Here is the simplest possible call — listing your services — in three languages.

curl

curl -X GET "https://api.simpletelecom.com.au/v1/api/services" \
  -H "Authorization: Bearer st_your_token_here"

JavaScript (fetch)

const token = "st_your_token_here";

const res = await fetch("https://api.simpletelecom.com.au/v1/api/services", {
  headers: { Authorization: `Bearer ${token}` },
});

const { data, meta } = await res.json();
console.log(`Found ${meta.total_records} active services`);
for (const s of data) {
  console.log(s.service_id, s.service_number, s.service_type);
}

PHP (cURL)

<?php
$token = "st_your_token_here";
$ch = curl_init("https://api.simpletelecom.com.au/v1/api/services");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $token"],
]);
$response = json_decode(curl_exec($ch), true);
foreach ($response['data'] ?? [] as $service) {
    echo $service['service_number'] . " (type {$service['service_type']})\n";
}

Rate limiting

To protect the platform, requests are rate-limited. The limit is communicated in three response headers:

| Header | Meaning | |---|---| | X-RateLimit-Limit | Maximum requests allowed in the current window | | X-RateLimit-Remaining | Requests still available in the window | | X-RateLimit-Reset | Unix timestamp when the window resets |

If you exceed the limit you receive 429 too_many_requests. See Error handling for how to back off gracefully.

Token best practices

• Keep tokens server-side only. Never ship a token inside client-side JavaScript that your visitors can read; proxy requests through your backend instead.
• Restrict what logs capture. Tokens look like st_... — make sure your logging and error tools redact the Authorization header.
• Scope by secret. If you run multiple environments, generate a separate token per environment so you can revoke one without taking down the others.
• Rotate on personnel change. Revoke and regenerate whenever someone with access leaves your team.
• Revoke when unused. If an integration is retired, revoke its token rather than leaving a live credential around.

Related

• Your services — the first thing to call once authenticated.
• Error handling — what happens when authentication fails.
• Quickstart — walk the full flow end to end.