API Key Authentication
All Open API requests require an API key in the Bearer token format.
Authorization: Bearer osk_megamart_a1b2c3d4e5f6g7h8...
Issuing an API Key
Prerequisites
- Tenant administrator (admin) privileges required
- Open API must be enabled for the tenant in the admin panel
Issuance Steps
- Log in to the tenant page as an administrator
- Click Open API from the profile menu
- Click the Issue New API Key button
- Choose a key name and expiration period
- Copy the issued key and store it in a safe place
The API key is shown only once at the time of issuance. You cannot view it again later, so make sure to store it securely.
Expiration Options
7 days, 14 days, 30 days, 60 days, 90 days, 180 days, 365 days, or permanent
Revoking a Key
Revoke any key that is no longer in use immediately:
- Check the key list on the Open API page
- Click the Revoke button for the target key
- Select Revoke in the confirmation modal
All use is halted immediately after revocation, so before revoking make sure to check for any applications connected to the key and issue a new key in advance.
Key Types
API keys are issued in two types based on their purpose, and accessible endpoints are separated.
| Type | Prefix | Purpose | Accessible | Blocked |
|---|
| Client SDK | osk_ | iOS/Android, web and other clients | persona, chat/, events, data | chat/completions |
| REST API | osr_ | Server-to-server integration | chat/completions | persona, chat/, events, data |
GET /v1/models is a common endpoint — the returned models differ depending on the key type.
Select the type via the tab when issuing on the tenant Open API page.
Accessing an endpoint with the wrong key type returns 403 Forbidden.
Scopes
The scopes assigned differ by key type.
Client SDK (osk_)
| Scope | Accessible Endpoints |
|---|
persona | /v1/persona/** |
chat | /v1/chat/{persona_id}/** |
data_ingest | /v1/data/events |
REST API (osr_)
| Scope | Accessible Endpoints |
|---|
chat | /v1/chat/completions |
analytics | /v1/usage |
Common
| Endpoint | Description |
|---|
/v1/models | Returns the models available for the key type |
Error Responses
| HTTP Code | Cause |
|---|
| 401 | Missing API key, invalid key, or expired key |
| 403 | Tenant has Open API disabled, or insufficient scope |
{
"success": false,
"message": "Invalid or expired API key"
}
Security Recommendations
- Do not include API keys directly in source code
- Use environment variables or a secret manager
- For iOS apps, store keys in the Keychain
- On the server side, manage keys via environment variables
- Revoke any unneeded key immediately
