Authentication
API keys, headers, org binding, and environments
SDKs authenticate as machines using API keys. Browser cookie sessions are for the portal only — keep keys on your server.
Portal
API keys are created and managed in the portal under API keys. The SDK reads the same key from your environment.
Create a key
- Open the portal → API keys.
- Create a key for the active organization.
- Choose a role (permissions) and optionally scope it to one app.
- Copy the secret once (
sk_test_…for sandbox apps,sk_live_…for production apps).
Environment variable
Both SDKs use the same variable:
export OLEQFILES_API_KEY=sk_live_…| SDK | Init |
|---|---|
@oleq-ai/file-manager | new OleqFiles() |
OleqAI.FileManager (.NET) | new OleqFilesClient() |
The key must start with sk_test_… or sk_live_…. Sandbox and production share the same API host (https://uploadspi.oleq.app); the prefix is what ties the key to sandbox or production apps.
Send the key
The SDKs set this for you. Raw HTTP accepts either header — see HTTP API:
x-api-key: sk_live_…or
Authorization: Bearer sk_live_…Organization binding
Each key is bound to one organization via metadata. You usually do not need x-organization-id. If you send it, it must match the key’s org.
App scope
If the key is scoped to an app, every request that includes an appId must use that app. Unscoped keys can access all apps in the org (subject to role permissions).
Roles & permissions
Keys inherit CASL grants from the assigned role (for example File::create, App::read). Assign the least privilege that still lets your service upload and manage files.
Sandbox vs production apps
Apps have an environment: sandbox or production.
- Sandbox apps — use with
sk_test_…keys. Files are temporary (see Concepts). - Production apps — use with
sk_live_…keys. Files are permanent.
Override baseUrl / BaseUrl only for local development.