This guide explains how AISentinel authenticates users and systems, how to configure Single Sign-On (SSO), how to manage tenant-scoped API keys and service accounts, and how to audit and rotate credentials safely. It’s written for Portal users and tenant administrators — operator-only instructions (like deployment environment variables) are documented elsewhere.
Key concepts you'll find below:
If you need operator-level details (KMS configuration, secrets manager integration), see Encryption & BYOK and Configuration Management.
All authentication events are audited and visible in tenant audit logs.
Overview:
What you can do in the Portal (UI) vs API:
POST /tenants/{tenant}/sso-test).POST /tenants/provision-sso when you need to persist secrets or run the automated OIDC discovery and validation.Quick steps (high level):
https://<HOST>/api/auth/callback/sso or the portal’s callback path.POST /tenants/provision-sso (or the Admin UI form) to store the sensitive client_secret. This call performs OIDC discovery and can optionally perform a real token exchange when confirm_test is true.POST /tenants/{tenant}/sso-test) and then attempt a sign-in.Endpoints used by the Portal:
Troubleshooting:
issuer or discovery endpoint is correct.API keys are the recommended mechanism for programs and automation. Keys are scoped to a tenant and can be created and managed via the Dashboard and API.
Typical uses:
Key lifecycle and actions (Portal features map to the following API endpoints):
POST /api/keys (UI creates keys for the current tenant; you can set name, expires_in_days or expires_at, allowed_rulepacks, and issue_renewal_token).GET /api/keys — shows status (valid/expiring_soon/grace/expired) and allowed_rulepacks.DELETE /api/keys/{key_id} — immediate revocation of the credential.POST /api/keys/{key_id} — issue a new secret; the previous key stops working.POST /api/keys/{key_id}/extend — increase expiration or set a new expiry date; request a renewal_token for automation.POST /api/keys/rotate-expiring — bulk rotation with optional per-key renewal_tokens issued.POST /api/keys/{key_id}/rulepacks — limits a key to only work with a specific subset of rulepacks.Important properties and behavior:
expires_at and will enter a warning/expiring_soon state before going into grace and then expired. You can extend keys from the UI or API.issue_renewal_token, the API returns a one-time renewal_token string (the server stores a hashed digest). Treat it like a sensitive secret and store it in a secure secret manager. Note: renewal tokens are an audit and automation artifact (useful when rotating keys) but they are not a replacement for tenant authentication — actual API calls to extend or rotate keys still require proper authentication.system_generated (used for automatic signups or backend processes). These can have different default expiration durations than user-created keys.allowed_rulepacks to restrict a key’s scope to a limited set of rulepacks. Attempting to run other rulepacks with a scoped key will result in authorization errors.Developer examples (quick):
Create a key (cURL):
curl -X POST "https://your-aisentinel-host/api/keys" \
-H "Authorization: Bearer <YOUR_FRONTEND_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"name": "automation-key", "expires_in_days": 30, "allowed_rulepacks":["default"], "issue_renewal_token": true}'
Extend an existing key using a TTL extension (the response can include a renewal_token):
curl -X POST "https://your-aisentinel-host/api/keys/<KEY_ID>/extend" \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{"extend_by_days": 30, "issue_renewal_token": true}'
Rotate expiring keys in bulk (Admin/Owner flows):
curl -X POST "https://your-aisentinel-host/api/keys/rotate-expiring" \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{"threshold_days": 7, "issue_renewal_token": true, "limit": 100}'
Create a key from a typical SDK (Python):
from aisentinel import Client
client = Client(api_key="TENANT_API_KEY")
new_key = client.keys.create(name="automation", expires_in_days=30, allowed_rulepacks=["default"]) # this call is proxied via the Portal API
print("Created key last4:", new_key.last4)
Create a key (JavaScript / Fetch):
const payload = { name: 'automation-key', expires_in_days: 30, allowed_rulepacks: ['default'], issue_renewal_token: true };
const res = await fetch('/api/keys', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) });
if (!res.ok) { throw new Error('Failed to create key'); }
const newKey = await res.json();
console.log('Created key last4:', newKey.last4, 'renewal token:', newKey.renewalToken ?? newKey.renewal_token);
Mint an execution token (JavaScript example talking to Portal admin API):
const payload = { tenant: 'demo-tenant', ttl: 300 };
const res = await fetch('/api/admin/tokens/mint', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload) });
const j = await res.json();
console.log('Execution token (short-lived):', j.token);
Use the Go SDK with a tenant API key (example uses the governor package):
package main
import (
"context"
"fmt"
governor "github.com/aisentinel/aisentinel-go-sdk"
)
func main() {
cfg := governor.Config{APIKey: "YOUR_TENANT_API_KEY"}
g, err := governor.New(cfg)
if err != nil {
panic(err)
}
ctx := context.Background()
// Example: evaluate a candidate using the governor client (refer to Go SDK examples in aisentinel-go-sdk/examples)
res, err := g.Evaluate(ctx, governor.EvaluateRequest{ /* ... */ })
if err != nil {
panic(err)
}
fmt.Printf("Evaluate response: %+v\n", res)
}
SDK note: The SDK examples in frontend/docs/sdk/README.md show how to create a client with an API key. Use a rotating key provider for long-lived automation secrets.
When an operation requires explicit approval (for example, a Python runtime execution or other side-effecting operations), the platform uses short-lived execution tokens.
POST /admin/tokens/mint (the UI has a Mint Token helper). The call requires that the API key making the request has mint_execution_tokens permission.Tenants can review role restrictions in the Dashboard under Team Management. Use the Roles & Privileges doc to match roles with operations.
OFFLINE_ENCRYPTION_KEY or use a tenant-managed key to encrypt exports.allowed_rulepacks to limit damage from token leakage.issue_renewal_token when automation requires rotation.POST /api/keys/rotate-expiring for automation.POST /tenants/provision-sso (Admin) or via your tenant config, and that your IdP allows the Portal callback URL.POST /api/keys/{id}/extend to extend or rotate; or POST /api/keys/{id} to regenerate.