Authentication

Every request carries an API key. A key belongs to one organisation, has the scopes you give it, and can be revoked at any time.

Sending the key

Put the key in the Authorization header as a bearer token. Keys start with tvx_live_.

Authorization: Bearer tvx_live_...

Never put the key in the address. A request that carries one in the query string is refused with credentials_in_url, because addresses end up in logs.

Creating a key

Create keys in your dashboard. Turn on two-step login for your own account first; keys cannot be made without it. The full key is shown once, when you create it. Travixor Global keeps only a hash, so a lost key cannot be recovered: make a new one and revoke the old one.

When you create a key you choose its scopes, and you may also set an expiry date and a list of IP addresses it may be used from. An organisation can hold up to 20 active keys. Give each system its own key, so you can revoke one without touching the others.

Scopes

A key can only do what its scopes allow. A route that needs a scope the key lacks answers 403 with insufficient_scope.

A key that only shows packages on your website needs catalog:read and nothing else. A key that can buy needs orders:write, plus orders:read to follow the order and esims:read if you read eSIMs on their own.

Keeping a key safe

• Use keys on your server only. Never put one in a web page, a mobile app or a public repository.
• Read the key from an environment variable or a secret store, not from your source code.
• Restrict a key to your server's IP addresses when you can. A request from any other address answers 403 with ip_not_allowed.
• If a key may have leaked, revoke it in the dashboard. It stops working at once.
• Browsers will not let a web page call the API, on purpose.

Checking a key

curl https://api.travixorglobal.com/v1/organization \
  -H "Authorization: Bearer $TRAVIXOR_API_KEY"

const res = await fetch('https://api.travixorglobal.com/v1/organization', {
  headers: { authorization: `Bearer ${process.env.TRAVIXOR_API_KEY}` },
})
console.log(res.status, await res.json())

import os

import requests

res = requests.get(
    "https://api.travixorglobal.com/v1/organization",
    headers={"Authorization": f"Bearer {os.environ['TRAVIXOR_API_KEY']}"},
    timeout=30,
)
print(res.status_code, res.json())

A wrong, expired or revoked key answers 401 with invalid_api_key. An organisation that is not approved, or has been suspended, gets 403 with organization_not_approved.