API Key Authentication
All Open API requests require a Bearer token:
Authorization: Bearer osk_megamart_a1b2c3d4e5f6g7h8...
Creating an API Key
Prerequisites
- Tenant admin role required
- Open API must be enabled for the tenant by the system administrator
Steps
- Log in to the tenant page as an admin
- Click Open API in the profile menu
- Click Create API Key
- Enter a key name and select an expiration period
- Copy the generated key to a safe location
The API key is shown only once at creation time. It cannot be retrieved later.
Expiration Options
| Option | Use Case |
|---|
| 7 days | Testing/development |
| 14 days | Short-term projects |
| 30 days | Default |
| 60 / 90 days | Medium-term |
| 180 / 365 days | Long-term production |
| Never expires | Permanent keys |
Key Format
osk_{tenant_code}_{random_hex_64}
Key Management
Revoking a Key
Revoke unused keys immediately via the Open API page.
Revoked keys are immediately unusable and cannot be restored.
Key States
| State | Description |
|---|
| Active | Normal operation |
| Expired | Past expiration date (automatic) |
| Revoked | Manually revoked |
Scopes
| Scope | Accessible Endpoints |
|---|
chat | /chat/completions, /models |
data_ingest | /data/events |
analytics | /usage |
Error Responses
| HTTP Code | Cause |
|---|
| 401 | Missing key, invalid key, expired key |
| 403 | Open API disabled for tenant, insufficient scope |
Security Best Practices
- Never include API keys in source code
- Use environment variables or secret managers
- Store in iOS Keychain for mobile apps
- Revoke unused keys promptly
