Overview
API keys authenticate server-to-server requests. Create and manage them in Dashboard → API keys; never expose a key in browser code, mobile applications, logs, or public repositories. Send a key to API endpoints with either Authorization: Bearer $BAR9_API_KEY or X-API-Key: $BAR9_API_KEY.
curl https://api.bar9.dev/v1/messages \
-H "Authorization: Bearer $BAR9_API_KEY"
Every key is permanently bound to test or production. Test keys call sandbox SMS and OTP endpoints without sending or charging. Production keys call live endpoints only after the account's production access is approved. Campaign and SenderID management also require a production key; audience and template management accept either environment.
Create a key in the dashboard
- Switch the dashboard to the Test or Production environment.
- Open API keys and start creating a key.
- Enter a name, keep the current environment, and select only the scopes the integration needs.
- Copy the plaintext key shown once and store it immediately in a server-side secret manager. It cannot be retrieved later; the dashboard only lists metadata such as name, key prefix, environment, scopes, and creation date.
When no management scope is selected, a key receives only the default scopes: sms:send, sms:read, otp:create, and otp:read. Production keys stay unusable until production access is approved.
Request production access
Open Production access in the dashboard and submit the business details for review, including company name, website, business address, legal status, and tax identification number. The account status moves from not_requested to pending, then to approved or rejected. A rejected request can be resubmitted. Production keys, campaigns, and SenderID operations stay blocked until approval.
Supported permissions
Read and write permissions are independent; neither implies the other. Management permissions are never granted by default.
| Permission | Allows | Environment |
|---|---|---|
sms:send |
Submit one SMS. | Matching endpoint |
sms:send:bulk |
Submit SMS batches. | Matching endpoint |
sms:read |
List and retrieve SMS messages. | Matching endpoint |
otp:create |
Create OTP sessions. | Matching endpoint |
otp:read |
Retrieve OTP session state without exposing its code. | Matching endpoint |
marketing:audiences:read |
List marketing audiences and their members. | Test or production |
marketing:audiences:write |
Create, update, and delete audiences and members. | Test or production |
marketing:campaigns:read |
List campaigns and retrieve delivery results. | Production only |
marketing:campaigns:write |
Submit campaign snapshots for back-office review. | Production only |
templates:read |
List message-template submissions and decisions. | Test or production |
templates:write |
Submit and update message templates for review. | Test or production |
sender-ids:read |
List SenderID applications and decisions. | Production only |
sender-ids:write |
Submit SenderID applications for review. | Production only |
Unknown permissions are rejected with 400 validation_error; no key is created. OTP code verification is a public end-user operation and has no API-key permission.
Manage existing keys
Filter the dashboard key list by environment to audit which integration owns each key. Revocation is permanent: deleting a key stops every request made with it, which then returns 401. If a key leaks, revoke it immediately and create a narrowly scoped replacement.
Common errors
| Status | Typical cause |
|---|---|
400 |
Unknown permission selected when creating the key. |
401 |
Missing, revoked, or invalid API key. |
403 |
Wrong key environment, missing scope, or unapproved production access. |