API Keys and Environments

Overview

API keys authenticate server-to-server requests. Create and manage them with an authenticated dashboard session; never expose a key in browser code, mobile applications, logs, or public repositories. Send a key to developer endpoints with either Authorization: Bearer $BAR9_API_KEY or X-API-Key: $BAR9_API_KEY.

Every key is permanently bound to test or production. Test keys can call sandbox SMS and OTP endpoints without sending or charging. Production keys can 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.

POST /v1/api-keys

Create a key with a dashboard session:

curl https://api.bar9.dev/v1/api-keys \
  --cookie "$BAR9_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production backend",
    "environment": "production",
    "scopes": [
      "sms:send",
      "sms:read",
      "templates:read",
      "marketing:campaigns:write"
    ]
  }'

name is required. environment is test or production and defaults to test. Production key creation returns 403 until production access is approved. scopes must contain at least one supported value when supplied; duplicates are removed. An omitted or empty array receives only the default scopes: sms:send, sms:read, otp:create, and otp:read.

The response is 201 Created. The plaintext key is returned once and cannot be retrieved later. Store it immediately in a server-side secret manager. Other fields include id, name, key_prefix, environment, scopes, created_at, and nullable last_used_at and revoked_at timestamps.

Supported permissions

Read and write permissions are independent; neither implies the other. Management permissions are never granted by default.

Unknown permissions are rejected with 400 validation_error; no key is persisted. OTP code verification is a public end-user operation and has no API-key permission.

GET /v1/api-keys

List keys belonging to the current dashboard user:

curl "https://api.bar9.dev/v1/api-keys?environment=test" \
  --cookie "$BAR9_SESSION_COOKIE"

The optional environment filter accepts test or production. The response never contains plaintext keys or key hashes.

DELETE /v1/api-keys/:api_key_id

Revoke one of the current user's keys. Success returns 204 No Content. Revocation is permanent; subsequent requests with that key return 401. Unknown keys and keys belonging to another account return 404.

GET /v1/environments/production-access

Return the current account's production-access status: not_requested, pending, approved, or rejected. The response also includes submitted business details and review timestamps when available.

POST /v1/environments/production-access/requests

Submit or resubmit a production-access request:

{
	"company_name": "Example SARL",
	"website": "https://example.dz",
	"business_address": "1 Example Street, Algiers",
	"legal_status": "sarl",
	"commercial_register": "optional",
	"tax_identification_number": "001612345678901",
	"statistical_identification_number": "optional"
}

company_name, an HTTP(S) website, business_address, legal_status, and tax_identification_number are required. Supported legal statuses are auto_entrepreneur_freelancer, eurl, sarl, snc, spa, spas, and association. Success returns 202 Accepted with pending status. Pending or approved requests are idempotent; rejected requests can be resubmitted.

Common errors