Authentication

Trackly SMS API requests can use an API key scoped to your account. Create and manage these keys from the dashboard. Registration preparation instead requires an API-audience bearer with owner-approved trackly.registration scope: see delegated OAuth for direct REST access without MCP and its rollout requirements. Ordinary API keys do not authorize registration preparation. New-customer setup creation is anonymous; setup status uses the request’s limited bearer capability and works before login. That token does not authenticate an account or authorize a send. Keys with requireSendConfirmation enabled require human approval for SMS. Direct SMS/raw SMS, email, OTP, and send-enabling schedule, campaign, contact double-opt-in, and journey operations return 403 confirmation_required. SMTP submission is also blocked. Reads, stop, and unsubscribe remain available. Check api_key.send_policy.require_confirmation on Who Am I. Voice Calls is outside this workflow. API keys follow the format trk_[32-char-alphanumeric] (e.g., trk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6). A key created with sandbox: true is a sandbox key. SMS sends are simulated without carrier delivery or message billing, while account reads return real data and single-send simulations may invoke configured webhooks. Enable sandbox in Settings > API Keys. Check the account, policy, and mode through GET /v2/auth/whoami; do not infer mode from the key prefix. A key can be paused from Settings > API Keys or by the key itself via POST /v2/auth/api-keys/self/pause. Subsequent API requests with a paused key fail authentication with 401 invalid_credentials. Only a workspace owner can resume it in the dashboard, after reviewing its current pause and settings.

Getting Your API Key

Navigate to API Keys

Log into the Trackly SMS Dashboard and go to Settings > API Keys

Create a New Key

Click Create API Key and give it a descriptive name (e.g., “Production API”, “Development”)

Copy Your Key

Copy the API key immediately - it won’t be shown again

Keep your API keys secure. Never commit them to version control or expose them in client-side code.

Using Your API Key

Include your API key in the X-Api-Key header for authenticated SMS API requests:

curl -X POST https://api.tracklysms.com/api/v2/send \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155551234", "body": "Hello!", "list_number": "+18005551234"}'

import requests

response = requests.post(
    "https://api.tracklysms.com/api/v2/send",
    headers={
        "X-Api-Key": "trk_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "to": "+14155551234",
        "body": "Hello!",
        "list_number": "+18005551234"
    }
)

const response = await fetch("https://api.tracklysms.com/api/v2/send", {
  method: "POST",
  headers: {
    "X-Api-Key": "trk_your_api_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+14155551234",
    body: "Hello!",
    list_number: "+18005551234",
  }),
});

As an alternative, you can pass the same key in an Authorization: Bearer <key> header (e.g. Authorization: Bearer trk_your_api_key_here). Send only one credential header: including both X-Api-Key and a nonempty Authorization header returns 401 invalid_credentials. X-Api-Key remains the recommended header for API keys; delegated OAuth uses Authorization: Bearer.

Keys for AI assistants

Create a dedicated key with Require send approval, appropriate allowed sending lists, and a daily live-send cap. Start in sandbox mode and store the secret in the client’s private credential settings, never in chat or tool arguments. HTTP MCP supplies X-Api-Key through that private configuration; the onboarding poll token is not a substitute. See Connect an AI assistant and Send with human approval. This SMS API connection is separate from the Public API v1 reference in the dashboard’s Developers section.

Authentication Errors

If authentication fails, you’ll receive a 401 Unauthorized or 403 Forbidden response: If your key has an IP allowlist, requests must originate from a listed address or CIDR range. This applies to sandbox keys too. An address outside the allowlist returns the same 401 invalid_credentials response as other unusable credentials. Check your application’s public outbound IP when troubleshooting.

Missing API Key
Invalid API Key
Expired or Rotated Key
Account Suspended

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

HTTP 401

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

HTTP 401

{
  "error": "Invalid credentials",
  "code": "invalid_credentials"
}

HTTP 401. A key that has passed its expiration date, or an old key whose rotation grace window has elapsed, is rejected with the same code as any other unusable credential — the response never distinguishes why a credential failed. Rotate or re-issue the key in Settings > API Keys.

API expiry and rotation-grace enforcement depends on rollout state. MCP independently refuses hold and execute operations when whoami reports a lifecycle denial. Pausing or deleting a key in Settings > API Keys prevents subsequent authentication immediately.

{
  "error": "Account is suspended",
  "code": "account_suspended"
}

HTTP 403. Returned when a valid API key’s owning account has been suspended by Trackly. The API key itself is still technically valid, but all requests are rejected until the account is reinstated. Contact support@tracklysms.com.

Suspension takes effect immediately: existing API keys start returning 403 Account is suspended on the next request.

Product Access Errors

Some endpoints are gated by per-account product entitlements. If your account isn’t enabled for a given product, requests to that product’s endpoints return 403 Forbidden with a {product}_not_enabled code:

{
  "error": "EMAIL product not enabled for this account",
  "code": "email_not_enabled"
}

The code follows the pattern {product}_not_enabled (e.g. email_not_enabled, partnerships_not_enabled). To enable a product on your account, contact support@tracklysms.com. SMS sending endpoints are enabled for all active accounts by default and do not return this error.

API Key Best Practices

Use Environment Variables

Store API keys in environment variables, not in code

Rotate Regularly

Create new keys periodically and revoke old ones

Separate Environments

Use different keys for development and production

Monitor Usage

Check the “Last Used” timestamp to detect unauthorized use

Managing API Keys

From the API Keys page in the dashboard, you can:

Action	Description
Create	Generate a new API key with a custom name
View	See key name, creation date, and last used timestamp
Configure	Set allowed sending lists, a daily send cap, and confirmation requirements
Pause	Stop subsequent authentication while preserving the key for owner review
Resume	Restore a paused key after owner review of its current settings; Voice permissions require current Voice approval, and explicit account or parent-account MFA policies still apply
Delete	Permanently revoke a key (cannot be undone)

Deleting an API key immediately invalidates it. Any requests using that key will fail with a 401 error.

Linking Discord with API Keys

If you use our Discord integration, you can link your Discord account to your Trackly account using an API key:

/sms link your_api_key_here

This allows you to:

View usage and balance from Discord
Create and manage support tickets
Receive real-time alerts

See Discord Integration for details.

Next Steps

V2 API Overview

Explore all v2 endpoints

Send First SMS

Send your first message

API Reference

V2 API Reference

Agent Account Setup (v2)

Agent Number Registration (v2)

Pending Sends (v2)

Partner Accounts (v2)

Messages (v2)

Contacts (v2)

Lists (v2)

Number Requests (v2)

Business Verification (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Usage & Billing (v2)

Data Import (v2)

Links (v2)

Clicks (v2)

Webhooks (v2)

Phone Validation (v1)

Voice Calls (v1)

API Reference (v1 - Deprecated)

Getting Your API Key

Using Your API Key

Keys for AI assistants

Authentication Errors

Product Access Errors

API Key Best Practices

Use Environment Variables

Rotate Regularly

Separate Environments

Monitor Usage

Managing API Keys

Linking Discord with API Keys

Next Steps

V2 API Overview

Send First SMS

​Getting Your API Key

​Using Your API Key

​Keys for AI assistants

​Authentication Errors

​Product Access Errors

​API Key Best Practices

Use Environment Variables

Rotate Regularly

Separate Environments

Monitor Usage

​Managing API Keys

​Linking Discord with API Keys

​Next Steps

V2 API Overview

Send First SMS

Getting Your API Key

Using Your API Key

Keys for AI assistants

Authentication Errors

Product Access Errors

API Key Best Practices

Managing API Keys

Linking Discord with API Keys

Next Steps