Skip to main content
DocsAPIAuthentication

Authentication

All API requests require authentication. Use an API key or JWT token.

Required Headers

Authorization: Bearer YOUR_API_KEY_OR_JWT
x-tenant-id: YOUR_TENANT_ID
Content-Type: application/json

Option 1: API Key

Generate an API key from Settings → API Keys in your dashboard.

Include it in the Authorization header:

curl -X GET https://beecastly.com/api/contacts \
  -H "Authorization: Bearer bcy_k1_abc123def456..." \
  -H "x-tenant-id: tenant_abc123"

Option 2: JWT Token

Obtain a JWT by calling the login endpoint:

POST /auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your_password"
}

// Response
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": { "id": "...", "email": "..." },
    "tenantId": "tenant_abc123"
  }
}

Use the returned token in subsequent requests.

Error Responses

401Unauthorized

Missing or invalid Authorization header.

{ "success": false, "error": "Unauthorized" }
403Forbidden

Valid token but insufficient permissions for this endpoint.

Security Best Practices

  • Never expose API keys in frontend code or Git repositories
  • Use environment variables to store keys server-side
  • Rotate keys regularly and revoke unused ones
  • Use scoped keys with minimal required permissions