Authentication

Theazo uses API keys for machine-to-machine access and RBAC roles for humans managing the platform. The two systems are independent — API keys authorize your SDK and backend calls; roles authorize dashboard and settings access.

API key types

Every platform gets two key environments. Both authenticate identically — the prefix determines whether the request provisions real compute or returns mock data.

Live keys

Live keys begin with th_live_. They provision real compute, record usage, and generate billing events. Use these only in production server-side code — never expose them in a browser bundle.

Test keys

Test keys begin with th_test_. They return realistic mock responses but never touch a provider, never record usage, and never generate billing events. Safe to use in CI, staging, and local development.

SDK usage

Pass your key to the constructor. The SDK attaches it as a Bearer token on every request automatically. The same constructor accepts both live and test keys.

import { Theazo } from 'theazo'

const theazo = new Theazo({
  apiKey: process.env.THEAZO_API_KEY!, // th_live_... or th_test_...
})

Direct API usage

If you are calling the REST API directly, supply the key in the Authorization header as a Bearer token. All endpoints require authentication.

curl https://api.theazo.com/v1/sessions \
  -H "Authorization: Bearer th_live_..." \
  -H "Content-Type: application/json"

curl https://api.theazo.com/v1/sessions \
  -H "Authorization: Bearer th_live_..." \
  -G \
  --data-urlencode "limit=20"

Managing keys

API keys are managed from Settings → API Keys in the dashboard. You can create multiple keys (e.g., one per service), label them, and revoke individual keys without rotating others.

The full key is shown exactly once — at creation time. After that, only the prefix (e.g., th_live_a1b2...) is visible. Store keys in a secrets manager immediately after creation.

# Rotate a key safely:
# 1. Create a new key in Settings → API Keys
# 2. Deploy with the new key
# 3. Revoke the old key once traffic confirms the new one is active

Authentication errors

A missing or invalid key returns a 401 with error code auth/invalid_key. A revoked key returns auth/key_revoked. Always include the requestId when contacting support.

import { TheazoError } from 'theazo'

try {
  const session = await theazo.sessions.forUser('user_123')
} catch (err) {
  if (err instanceof TheazoError) {
    console.log(err.code)      // 'auth/invalid_key'
    console.log(err.status)    // 401
    console.log(err.requestId) // 'req_...' — include in support tickets
  }
}

Role-Based Access Control (RBAC)

Every Theazo organization has members with roles. Roles control what actions a person can take via the dashboard and Next.js API routes. RBAC is for humans — not machines. When your backend calls the Theazo API with an API key, the key itself is the authorization and RBAC does not apply.

Roles

Permission matrix

Management plane vs data plane

Theazo has two distinct authorization planes. Understanding the distinction avoids confusion when reasoning about who can do what.

Team management

Manage your team from Settings → Team in the dashboard. Owners and admins can invite members, change roles, and remove members. All role changes take effect immediately.

Invite a member

curl https://your-dashboard.com/api/team \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "userId": "usr_abc123", "role": "member" }'

List members

curl https://your-dashboard.com/api/team

Change a member's role

curl https://your-dashboard.com/api/team/mem_abc123 \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

Remove a member

curl https://your-dashboard.com/api/team/mem_abc123 \
  -X DELETE

Transfer ownership

curl https://your-dashboard.com/api/team/transfer \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{ "newOwnerId": "mem_xyz789" }'

Edge cases

These constraints are enforced server-side. The dashboard prevents these actions in the UI, but the API also returns an error if you attempt them directly.