Dashboard

API Keys and Environments

Create scoped test and production keys in the dashboard and request production access.

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

  1. Switch the dashboard to the Test or Production environment.
  2. Open API keys and start creating a key.
  3. Enter a name, keep the current environment, and select only the scopes the integration needs.
  4. 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.