Create and manage Atom API tokens

Admin

The Atom API connects your own systems to Atomic. You can use it to manage services, numbers and sub-customers without carrying out each action in the portal. An API token identifies the account making each request.

This guide explains how account owners and authorised sub-users create, use and revoke tokens. For required request fields and endpoint examples, see the Atom API documentation.

Important: An Atom API token is different from an SMS service's API key. Use the Atom API token to manage services through the V1 API. Sending SMS messages uses the separate SMS API and a key issued for the SMS service.

Before you start

Sign in as the account owner or a sub-user whose role includes access to the API tab.
The API must be enabled for your portal. Contact support if the page says it is not switched on.
By default, an account can hold 5 active tokens, shared by the owner and its sub-users. This limit can change. Follow the limit shown on the page if another token cannot be created. Revoked tokens do not use a slot.
Grant API access only to people who need it. A sub-user's token can perform the same account-level API operations as the owner's token, even when that person's portal role does not show the corresponding pages.

Give a sub-user API access

Step 1: Go to Profile > Account Settings > Access Control.

Step 2: Under Access Control List, select Create ACL, or Manage on an existing ACL type.

Step 3: Enter a Type Name, tick API under Account Settings, then select Create (or save your changes).

Create Access Control with API ticked under Account Settings

Step 4: Under Sub Users, give the sub-user that ACL type. They can then open the API tab and create their own tokens.

Open the API page

Navigate: Profile > Account Settings > API

Step 1: Sign in to the Atomic portal.

Step 2: Open the profile menu in the top right corner and select Account Settings.

Profile menu open with Account Settings highlighted.

Step 3: Select the API tab.

Account Settings API tab with token generation form and API Tokens list selected in step 3

The page shows Generate API Token and the API Tokens list. If API access is disabled, you cannot create a new token. Previously issued tokens can still be listed and revoked by users who have access to the page.

If you cannot see the tab, please contact the customer support.

Create an API token

Step 1: Under Generate API Token, enter a Token name you will recognise later, such as Billing integration. The name must be no more than 255 characters.

Step 2: Click Generate token.

Generate API token form with the token name field and Generate token button highlighted

Step 3: In Copy your new API token, click Copy. Store the full token in a password manager or your system's secure credential store before leaving the page.

New API token panel with the one-time token and Copy button highlighted.

The new token appears in the API Tokens list with status Active.

API Tokens list showing the new token with Active status.

Warning: The full token is shown once only. Atomic cannot display it again. If you lose it, revoke that token and create another.

Tokens created on this page start with atk_ and have no scheduled expiry. They can be revoked at any time. Changes to the token holder's login status or access to an active customer account can also stop the token from being usable for account operations.

Use and check your token

Send the token in the Authorization header:

http

Authorization: Bearer <your API token>

The production base URL is:

text

https://atomic.atomtelecom.com.au/api/v1

Expand How to use an API token on the API tab for a reminder.

API tab with “How to use an API token” expanded, showing the Bearer authorization header format

To check a token, send a GET request to /auth/validate. This example uses a placeholder, not a real token:

bash

curl -H "Authorization: Bearer <your API token>" https://atomic.atomtelecom.com.au/api/v1/auth/validate

A successful response identifies the token holder in data.user. Check that data.user.customer_id is the intended account before using the token for account operations.

If customer_id is null, the token has not resolved to an active customer account. Contact support. A successful validation response alone does not prove that a service operation is available or authorised.

View and revoke tokens

The API Tokens list shows Name, Status, Token prefix, Created and Last used. Account owners also see Owner.

Account owners can view and revoke tokens created by users on their account.
Sub-users can view and revoke only their own tokens.
Each user creates their own tokens. The account owner does not generate a token on someone else's behalf from this page.

To revoke a token:

Step 1: Find the token in API Tokens. Check its name, prefix and owner where shown.

Step 2: Click Revoke.

API tokens table with the Revoke button highlighted for an active token

Step 3: In Revoke API token?, click Revoke token.

API token revocation confirmation dialog with the Revoke token button highlighted.

Step 4: Check that the token's status changes to Revoked.

API Tokens list with the token's Revoked status highlighted

After successful revocation, subsequent requests using that token are rejected. Revocation does not undo changes already made through the API.

Warning: Revoking a token stops integrations that still use it. For a planned replacement, update and check the replacement token before revoking the old one. If a token is exposed, revoke it promptly.

Replace a token

Step 1: Create a replacement token on the API tab and store it securely.

Step 2: Update the system that uses the old token.

Step 3: Check the replacement with /auth/validate and confirm the expected account. Check an appropriate read-only endpoint required by your integration as well.

Step 4: Revoke the old token once the replacement is working.

If the account has reached its active-token limit, free an unused slot first. Do not revoke a token used by another system without arranging its replacement. A sub-user who cannot free a slot should ask the account owner.

When a team member leaves

Step 1: As the account owner, open Account Settings > API.

Step 2: Identify and revoke the departing person's tokens in API Tokens.

Step 3: Replace credentials in any systems that still used those tokens.

Removing the person's access to the API tab does not revoke tokens they already created. Revoke those tokens explicitly rather than relying on a portal-permission change.

Keep tokens safe

Treat each token like a password. Anyone holding it may be able to act on the account.
Keep tokens in a secure credential store, not in public code, shared documents, screenshots or emails.
Limit who can read your integration's credentials and avoid logging the full Authorization header.
Use recognisable token names so the account owner can identify the systems and people using them.
Review unused tokens and revoke those no longer needed.

What the API can manage

Use the endpoint reference for the required fields, permissions and restrictions of each operation.

7 of 7 rows


Voice services	Create SIP Trunk, Hosted Voice and Microsoft Teams Direct Routing services; list, view, update and delete services.
SIP endpoint and trunks	View connections. For SIP Trunk services, update the SIP endpoint and VoIP password and create, update or delete incoming and outgoing trunks.
Numbers	Browse available numbers and localities, order numbers onto a voice service, view attached numbers, change supported delivery settings and remove numbers.
SMS numbers	Browse, order, list, view and remove Australian mobile numbers used for SMS only, with no voice service. A voice number order can also add an Australian mobile number as a Sender ID on an SMS service.
SMS services	Create, view, update and delete SMS services. Manage supported numeric Sender IDs and SMS API keys. Brand-name registration is carried out in the portal, not through the add-Sender-ID endpoint.
Sub-customers	Create, view, update and delete sub-customers and manage their portal login.
Service plans	List and view the plans available to the account.

Common workflows

These are workflow outlines. Use the API documentation for request bodies, available plans and the required fields before running operations that create, change or remove services.

Set up a SIP Trunk service

Step 1: If needed, create a sub-customer with POST /sub-customers.

Step 2: Choose a plan from GET /service-plans and create the service with POST /services/voice/sip-trunk.

Step 3: Configure the SIP endpoint with PATCH /services/voice/{id}/sip-endpoint or configure the required incoming and outgoing trunks. To receive calls, the service needs SIP registration enabled or a suitable incoming trunk.

Step 4: Browse numbers with GET /services/voice/{id}/dids/available. For geographical numbers, first obtain a locality using GET /services/voice/{id}/dids/zones and the required country and type.

Step 5: Order the selected numbers with POST /services/voice/{id}/dids, using the country, type and connection appropriate to the service.

Step 6: Check the attached numbers with GET /services/voice/{id}/dids.

Order numbers

Enter every number in international format without the +. Domestic formats starting with 0 are not accepted.
Choose numbers from the available-number response and use those returned values when placing the order.
The current reference covers Australia and New Zealand. Available types depend on the country and current supply.
Australian geographical numbers can be ordered as blocks of 10 or 100. Send one block per request: the first number returned for that block and the same block size used when browsing.
Single-number orders can contain up to 100 numbers per request.
To use an Australian mobile number for calls and SMS, include sms_service_id in a single-number voice order. After each number is attached to the voice service, it is also added as a Sender ID on that SMS service. The SMS service must belong to the account, be active and be under the same sub-customer as the voice service. Otherwise the order is refused before anything is ordered.
201 means at least one number was created and none failed. 200 means all requested numbers were already attached. 207 means one or more numbers failed; read every number's result. A completely failed batch may still return 207 with success=false.
Repeating the same number order does not provision or charge already attached numbers again. Do not assume this protection applies to other API operations.

Order a number for SMS only

Use this when the number only sends and receives SMS. No voice service is needed, and calls to the number do not connect.

Step 1: Browse numbers with GET /services/sms/{id}/dids/available. Use contains to match digits and limit to choose how many are returned.

Step 2: Order the selected numbers with POST /services/sms/{id}/dids, sending each number exactly as the available-number response returned it in dids. Each number becomes a Sender ID on the SMS service straight away.

Step 3: Check the service's numbers with GET /services/sms/{id}/dids.

Only Australian mobile numbers can be ordered this way, up to 100 per request. The SMS service must be active.
201 means at least one number was created and none failed. 200 means all requested numbers were already on this SMS service. 207 means one or more numbers failed; read every number's result.
If a number's result is ACTIVATION_INCOMPLETE or NOT_ATTEMPTED, do not order it again. Atom support completes it.
A failed number that was tried includes a ref. Quote it when you contact support.

Remove a number

Warning: Number removal stops calls and charges for that number. It cannot be undone through the API. Remove a number only when it is no longer needed.

Step 1: Obtain the number's did from the service's number list: GET /services/voice/{id}/dids for a voice service, or GET /services/sms/{id}/dids for a number ordered for SMS only.

Step 2: Send DELETE /services/voice/{id}/dids/{didId}, or DELETE /services/sms/{id}/dids/{didId} for a number ordered for SMS only. Replace {didId} with that did value, not an internal database ID. For a block, use the complete range returned by the service.

Step 3: 202 means the number has been removed from the service and carrier release is in progress. Calls and billing stop straight away. A single-number lookup can show disconnecting while release finishes.

A block must be removed as a whole. Naming just one number within a block returns 409. Repeating an already completed or in-progress removal returns 200.

Removing a number ordered for SMS only also stops its SMS straight away and removes its Sender ID from the SMS service. Repeating a completed removal returns 200. While a removal is still finishing, a repeat returns 409; try again after a few minutes. An SMS service can be deleted once all its numbers are removed.

Set up SMS

Step 1: Create an SMS service with POST /services/sms.

Step 2: Use GET /services/sms/{id}/senders/available to find an eligible numeric Sender ID.

Step 3: Add the selected numeric Sender ID with POST /services/sms/{id}/senders, following the reference's type=vmn and value requirements. For a brand name, use Register Brand Name in the SMS service's portal settings instead.

Alternatively, order an Australian mobile number for the service with POST /services/sms/{id}/dids (see Order a number for SMS only). The number becomes a Sender ID automatically, so Step 3 is not needed for it.

Step 4: Create the service's SMS API key with POST /services/sms/{id}/api-keys and store the returned full key immediately. It is shown once only.

Step 5: Use that service key with the separate Atom SMS API reference to send messages. The V1 provisioning API does not send SMS messages itself.

Request limits

All tokens belonging to the same account share one request allowance. Creating more tokens does not increase it.

The default allowance is 20 requests per minute, but the current allowance can change. Build your integration around the returned headers rather than a fixed request rate:

3 of 3 rows


`X-RateLimit-Limit`	The number of requests allowed in the current window.
`X-RateLimit-Remaining`	The remaining allowance.
`X-RateLimit-Reset`	The Unix timestamp when the allowance resets.

These headers are normally included on counted responses, not guaranteed on every response. If they are absent, treat the allowance as unknown and keep your existing request pace.

If a request returns 429, wait for the number of seconds in Retry-After before trying again. Slow down as the remaining allowance approaches zero.

Troubleshooting

11 of 11 rows


400	Read `message` and any `errors`. Correct the invalid fields or values before retrying.
401	Check `Authorization: Bearer <your API token>`, the full token value and whether the token is revoked. The token holder's login must also be active.
403	The token cannot access this account, operation or resource. Confirm the account scope and resource ID. A removed account link or inactive customer account can also prevent account operations.
404	Check the endpoint path and whether the requested resource exists. A missing resource can return 404 even when the path is correct.
405	Use a method listed in the response's `Allow` header and the endpoint reference.
409	Read `message` and resolve the operation's stated conflict or restriction.
410	V1 password-login, refresh and logout endpoints have been removed. Use a token created in the portal.
415	The endpoint requires a JSON content type. Send `Content-Type: application/json` and a valid JSON body. Invalid JSON can instead return 400.
429	Wait for `Retry-After` and reduce the request rate.
500	An internal error occurred. For a create, change or delete request, check the resulting state before retrying. If the outcome is unclear, contact support instead of repeatedly submitting it.
503	Read `message`. If it says the API is unavailable or switched off, contact support. Do not assume a new token will enable the API.

V1 JSON responses use success, data, message, timestamp and api_version. Error responses with an HTTP status of 400 or higher also include code and may include errors.

Need help?

See the Atom API documentation or lodge a ticket through Get Help in the portal. Include the request time, endpoint, HTTP status and a response with sensitive information removed. Never include the token or full Authorization header.

Was this article helpful?

Pay an Invoice or Top Up by Card

Port a mobile number with an SMS code

Receiving SMS