API keys and authentication

Every textbee API request carries your API key in the x-api-key header. You create and revoke keys in the API Keys panel of the dashboard. A key gives full access to your account, so keep it on your server and treat it like a password.

Send the key with each request

Add the header to every call. The base URL is https://api.textbee.dev/api/v1.

x-api-key: YOUR_API_KEY

There is no login call and no token to refresh. A request without the header, or with a wrong key, gets 401.

Create a key

1. Open the dashboard.
2. In the API Keys panel, click Generate API Key.
3. Copy the key and store it in a safe place.

The dashboard shows the key only once. After you close the dialog, you cannot view it again. If you lose a key, create a new one and revoke the old one.

The same dialog shows the key as a QR code. The textbee app scans that code to register a device. You can create one key for each phone and one for each application, so you can revoke one without affecting the others.

Check that your key works

GET /gateway/stats is a cheap call that returns your account totals. Use it to test a new key or a new environment before you send a message.

curl https://api.textbee.dev/api/v1/gateway/stats \
  -H "x-api-key: YOUR_API_KEY"

A working key returns 200 with this body:

{
  "data": {
    "totalSentSMSCount": 128,
    "totalReceivedSMSCount": 42,
    "totalDeviceCount": 1,
    "totalApiKeyCount": 2
  }
}

What 401 means

401 means textbee did not accept the key. There are three causes:

• The x-api-key header is missing. Check the header name and that your HTTP client sends it.
• The key is wrong. Check for a missing character or extra spaces from a copy and paste.
• The key is revoked.

The body looks like this:

{ "error": "Unauthorized", "code": "AUTH_INVALID" }

Do not retry a 401. The same request fails again until you fix the key.

Keep the key secret

A key has the same access as your account. It can send SMS from your phones, read all your messages and change your webhooks. Follow these rules:

• Keep the key on a server, in a serverless function or in a background job.
• Never put the key in a mobile app, a browser bundle or a public repository. Anyone who opens the app or the page can read it.
• Let your front end call your own server, and let your server call textbee.
• Store the key in an environment variable or a secret manager, not in source code.

Environment variable convention

Name the variable TEXTBEE_API_KEY. The code samples in these docs read it, and so does the textbee MCP server. Self-hosted instances also set TEXTBEE_BASE_URL.

export TEXTBEE_API_KEY="YOUR_API_KEY"

Where the key goes

Rotate a key

Rotate a key when it may have leaked, when a team member leaves, or on a fixed schedule. Rotation has no downtime if you follow this order:

1. Create a new key in the API Keys panel.
2. Deploy the new key to every place that uses the old one.
3. Check that each service works, for example with GET /gateway/stats.
4. Revoke the old key from its actions menu in the API Keys panel.

Revoking stops the key everywhere at once. Revoked keys stay listed under View revoked keys, and you can remove them from there.

Frequently asked questions

Can I limit a key to sending only?

No. Every key has full access to the account. To limit the impact of a leak, use a separate key for each service and revoke only the one that leaked.

How many keys can I have?

The dashboard lets you create more than one. totalApiKeyCount in GET /gateway/stats shows how many your account has.

Can I call the API from the browser?

No. The browser would expose the key to every visitor. Call textbee from your server and let the browser call your server.

Next steps

• Sending SMS
• Registering a device
• JavaScript SDK
• API reference