Authentication

API key types

The SDK supports three authentication modes, each matched to a session type.

| Key type | Prefix | Purpose | | --- | --- | --- | | Personal | sk_per_ | Interactive development by a named human user | | Service | sk_svc_ | Long-running automated systems (cron jobs, ingesters, backends) | | Agent | sk_agt_ | Autonomous agents (robots, IoT sensors, AI assistants with write access) |

Each type carries a distinct audit signature and distinct rate limits.

Creating a key

Web UI

Sign in at app.brrain.io → Settings → API Keys → Generate New Key. Choose the key type and the target workspaces. The key is shown once at creation time.

CLI

brrain keys create --type service --workspace legal-team --name "nightly-ingester"

API

key, err := client.Keys.Create(ctx, &sdk.CreateKeyInput{
    Type:       sdk.KeyTypeService,
    Name:       "nightly-ingester",
    Workspaces: []string{"legal-team"},
})

Rotating keys

Rotate on a schedule (every 90 days is a sensible default):

brrain keys rotate sk_svc_xxxxx --grace-period 7d

The old key continues to work during the grace period while you update dependents. After the grace period, it's revoked automatically.

Authentication flow

1. Client sends request with Authorization: Bearer <api-key>
2. Handler validates signature and retrieves session context
3. Request authorized against workspace policy
4. Audit log entry created (immutable)
5. Handler executes request and returns result

All traffic between SDK and Handler uses TLS 1.3. Inside the Handler, envelope encryption isolates tenant data — the master key never leaves the Vault.

Session management

Sessions are ephemeral contexts that bundle a key, workspace, and metadata.

session, _ := client.Sessions.Create(ctx, &sdk.CreateSessionInput{
    Workspace: "legal-team",
    Type:      sdk.SessionTypePersonal,
})
defer session.Close()

Sessions auto-close after 30 minutes of idle; use explicit Close() for cleanliness. Service and Agent sessions can be configured to persist indefinitely.

Token refresh and expiration

Access tokens are short-lived (15 minutes) and refreshed automatically by the SDK. Refresh tokens expire after 30 days. If a refresh fails (key rotated, workspace removed), the SDK surfaces a typed error:

if errors.Is(err, sdk.ErrAuthExpired) {
    // Prompt user or rotate service key
}

Security best practices

1. Never hardcode keys. Use environment variables or a secret manager.
2. Scope keys narrowly. A service key for the ingester shouldn't have admin privileges.
3. Rotate regularly. Automate rotation for service and agent keys.
4. Use distinct keys per environment. Dev, staging, and prod should never share keys.
5. Audit regularly. Every key has a usage report under brrain keys audit <id>.
6. Revoke on incident. One command invalidates a key globally within 5 seconds.