Skip to main content
TGO Business uses two authentication mechanisms depending on which API you’re calling. The Tenant API — where you send messages, manage sender numbers, and read usage — authenticates every request using an API key passed in the X-Api-Key header. The Central API — used for account-level operations like registering and logging in — uses a Bearer token returned at login. Most integrations only need an API key.

​
API keys

API keys are the primary way to authenticate requests to your Tenant API. Each key has a defined set of scopes that limit what it can do, and an expiry date after which it stops working.

​
Create an API key

You can create an API key from your dashboard under Settings → API Keys → New key, or by calling the API directly.
The full API key value is only shown once — at the moment of creation, or when you use the Show key action if your account uses encrypted storage. Copy and store it somewhere safe before closing the dialog.
To create a key via the API, send a POST request authenticated with your existing API key: 
curl -X POST "https://{tenant-domain}/api/v1/api-keys" \
  -H "X-Api-Key: {api_key}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production integration",
    "scopes": ["messages.send", "messages.read"],
    "expires_in_days": 90
  }'
The response includes a plain_text_key field containing the full API key. This field is only returned in this response — it will not appear again. 
{
  "id": 1,
  "name": "Production integration",
  "prefix": "tgo_",
  "scopes": ["messages.send", "messages.read"],
  "status": "active",
  "expires_at": "2026-07-24T00:00:00Z",
  "last_used_at": null,
  "plain_text_key": "tgo_••••••••••••••••••••••••••••••••"
}

​
Use an API key

Pass your API key in the X-Api-Key header on every Tenant API request: 
X-Api-Key: {api_key}
Accept: application/json

​
Scopes

When you create a key, you choose which scopes to grant. Assign only the scopes your integration needs.
ScopeWhat it allows
messages.sendSend messages and add sender numbers
messages.readRead message history
contacts.lookupCheck whether a number can receive messages
usage.readRead usage statistics and account limits
*All permissions

​
Key expiry

Set expires_in_days to a value between 1 and 365 when creating a key. The default is 90 days. After a key expires, requests using it return an authentication error. Rotate keys before they expire to avoid service interruption.

​
Revoke a key

To immediately invalidate an API key, send a DELETE request using its ID: 
curl -X DELETE "https://{tenant-domain}/api/v1/api-keys/{apiKey}" \
  -H "X-Api-Key: {api_key}" \
  -H "Accept: application/json"
Revoked keys cannot be re-activated. Create a new key if you need to restore access.

​
Bearer tokens

Bearer tokens are used to authenticate Central API requests — operations like logging in, registering, or managing your workspace. You receive a token in the response body when you call the login endpoint. Pass the token in the Authorization header: 
Authorization: Bearer {token}
Accept: application/json
To check your current tenant context (active user, organization, and subscription details), call: 
curl "https://business.tgo-eg.com/api/v1/me" \
  -H "X-Api-Key: {api_key}" \
  -H "Accept: application/json"
This endpoint returns your current user, API key metadata, organization details, and subscription status.
You do not need a Bearer token for day-to-day messaging operations. Those requests go to your Tenant API and use an API key instead.

​
Best practices

  • Use minimal scopes. Grant only the permissions your integration actually needs. A key used only to send messages should have messages.send, not *.
  • Rotate keys regularly. Set expiry dates and replace keys before they expire. Treat rotation as routine maintenance, not a response to incidents.
  • Never expose keys in client-side code. API keys must be kept server-side. Do not include them in browser JavaScript, mobile app binaries, or public repositories.