Assistiv Docs

Authentication

All API requests require an API key passed in the Authorization header. The key type determines what operations are allowed.

Authorization Header

Pass your API key as a Bearer token in the Authorization header on every request.

bash
curl https://api.assistiv.ai/v1/platforms/{platformId}/end-users \
  -H "Authorization: Bearer sk-plat_your_key_here"

API Key Types

PLATFORMsk-plat_*

Platform keys are used for management operations: creating end users, managing API keys, configuring LLM providers, topping up wallets, and managing agents/MCP apps.

Can access

  • Platform CRUD
  • End user management
  • API key management
  • LLM configuration
  • Agent management
  • MCP app configuration
  • Wallet operations
  • Budget management
  • Logs
END USERsk-eu_*

End-user keys are used for runtime operations: making chat completion requests, checking budgets, connecting MCP apps, and using tools.

Can access

  • Chat completions (inference)
  • Model listing
  • Budget checking
  • MCP tool connections & sessions

⚠Key type enforcement

Platform keys cannot access end-user-only routes (e.g. /v1/me/budget), and end-user keys cannot access platform management routes. Using the wrong key type returns a 403 Forbidden error.

Key Lifecycle

1

Creation

When you create a platform or end user, a default API key is auto-generated. You can also create additional keys via the API. The raw key is returned only once in the creation response.

2

Storage

The key is hashed with SHA-256 before storage. Only the first 8 characters (key_prefix) are stored in plaintext for identification.

3

Validation

On each request, the gateway hashes the provided key and looks up the matching hash. It checks is_active and expires_at before granting access. Results are cached in Redis for 60s.

4

Revocation

Delete or deactivate a key via the API. The Redis cache is invalidated immediately, so revocation takes effect within seconds.

Auth Context

Every authenticated request resolves to an auth context that includes:

typescript
interface AuthContext {
  platformId: string;       // Always present
  endUserId: string | null; // null for platform keys
  keyType: "platform" | "end_user";
  scopes: string[];
  keyId: string;
}

All database queries are automatically scoped to the platformId from the auth context, ensuring complete tenant isolation.