Authentication
Developer Docs

Authentication

Two ways to authenticate: user JWT tokens for dashboards, and API keys for server-to-server calls.

JWT BearerAPI KeysHMAC-signed

User auth

JWT

Bearer token

Server auth

API Key

ak_ + as_

JWT expiry

7 days

Configurable

Signature

SHA-256

HMAC

Overview

Pick the right auth for the job

There are two authentication mechanisms. Use the right one for the context — they're not interchangeable.

User JWT

For logged-in users

  • Issued on login
  • Represents a single user session
  • Expires after 7 days
  • Full tenant + role access

API Key

For server integrations

  • Created by admins
  • Scoped to specific permissions
  • Long-lived (up to 1 year)
  • No user context
Use JWT for anything a person does through your app. Use API keys for anything a machine does on behalf of your tenant.

User JWT authentication

For logged-in dashboard users

When a user logs in, our auth service returns a JWT token. Include it on every request in the Authorization header.

Login
bash
curl -X POST https://api.yourapp.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'
Response
json
{
  "success": true,
  "data": {
    "user": {
      "id": "507f1f77bcf86cd799439011",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "ADMIN",
      "tenant": {
        "id": "507f1f77bcf86cd799439012",
        "name": "Acme Corp",
        "type": "OFFICE"
      }
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Use the token on every request

bash
curl https://api.yourapp.com/api/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
7-day expiry

Tokens expire after 7 days by default

Signed with secret

Verified on every request

Tenant scoped

Contains tenantId + role

API Key authentication

For server-to-server integrations

API keys are long-lived credentials created by tenant admins. They're scoped to specific permissions and don't represent a user — only the tenant.

1Admin creates a key

Settings → API Keys → Generate New Key

2Copy key and secret

The secret is only shown once — save it immediately

3Use on every request

Send in Authorization or X-API-Key header

Two header formats

http
Authorization: Bearer ak_3f8a9b2c4d5e6f7a8b9c0d1e2f3a4b5c

# or

X-API-Key: ak_3f8a9b2c4d5e6f7a8b9c0d1e2f3a4b5c
Key format
ValuePrefixUse
keyak_Public — sent on every request
secretas_Private — signs webhook payloads
Never expose the secret in client-side code or commit it to git. Rotate immediately if leaked.

Auth headers reference

What to send and when

HeaderUsed withFormat
AuthorizationJWT or API KeyBearer <token>
X-API-KeyAPI Key onlyak_...
X-API-SecretAPI Key (optional)as_...

Full request with JWT

javascript
const res = await fetch('https://api.yourapp.com/api/users', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    'Content-Type': 'application/json',
  },
});

Full request with API key

javascript
const res = await fetch('https://api.yourapp.com/api/v1/public/users', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
});

Best practices

Do's and don'ts

Do
  • Store tokens in httpOnly cookies or memory
  • Use environment variables for API keys
  • Rotate keys on a schedule
  • Give API keys minimum permissions
  • Use HTTPS only
Don't
  • Commit API keys to git
  • Expose secrets in client-side code
  • Use API keys in browser apps
  • Share keys between applications
  • Reuse a single key for all integrations

Need help with auth?

Reach out with your tenant ID and the failing request (redact secrets).

Contact Support