Authentication

API keys

API keys are the primary authentication mechanism for server-side integrations. Every request to hybriDB must include an API key.

Authorization: Bearer sk-hdb-<your-key>

The SDK handles this automatically once you pass apiKey to the constructor:

const hdb = new HybriDBClient({
  baseUrl: 'https://hybridb.stellrai.com',
  apiKey:  process.env.HDB_API_KEY!,
});

Server-side only

Never expose your API key in client-side code, mobile apps, or public repositories. Use environment variables and ensure keys are only used from your backend.

Obtaining an API key

1. Sign up at stellrai.com/signup
2. Your first API key is issued during onboarding and shown once
3. Generate additional keys at Dashboard → Settings → API Keys

Key scopes

Each key can be scoped to limit its access. Always use the minimum scopes required.

// Example: trigger-only key for a payment service
{
  name:   'payments-service',
  scopes: ['decision:request', 'pipeline:trigger', 'reversibility:write'],
}

Full scope list: see Core Concepts → API keys and scopes.

JWT authentication (server-to-server)

For short-lived server-to-server calls, you can authenticate via JWT and receive a token pair:

const { access_token, refresh_token } = await hdb.authenticate({
  email:    '[email protected]',
  password: 'your-password',
});

Use hdb.refreshToken(refresh_token) before the access token expires (default TTL: 15 minutes).

API keys are preferred

For production integrations, API keys are simpler and more reliable than JWT flows. JWT is primarily used for user-facing dashboards and short-lived sessions.

JWKS endpoint

For verifying hybriDB-issued JWTs in your own services:

GET https://hybridb.stellrai.com/api/v1/auth/.well-known/jwks.json

const { keys } = await hdb.getJwks();

hybriDB uses EdDSA Ed25519 for JWT signing.