Learn how to authenticate with the OneApp API.
The OneApp API supports two authentication methods:
Short-lived tokens for user sessions. Best for web/mobile apps.
Long-lived keys for server-to-server. Best for backend services.
Include the token in the Authorization header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...curl -X GET "https://api.oneapp.io/api/v1/auth/user" \
-H "Authorization: Bearer YOUR_TOKEN"const response = await fetch('https://api.oneapp.io/api/v1/auth/user', {
headers: {
'Authorization': `Bearer ${token}`,
},
});Include the API key in the X-API-Key header:
X-API-Key: oa_live_abc123...curl -X GET "https://api.oneapp.io/api/v1/auth/user" \
-H "X-API-Key: YOUR_API_KEY"Important: API keys are shown only once at creation. Store them securely and never commit them to version control.
Limit API key permissions with scopes:
| Scope | Description |
|---|---|
| read:users | Read user profiles |
| write:users | Update user profiles |
| read:conversations | Read AI conversations |
| write:conversations | Create/update conversations |
| read:knowledge-bases | Read RAG knowledge bases |
| write:knowledge-bases | Manage knowledge bases |
| admin | Full access (use with caution) |
# .env.local
ONEAPP_API_KEY=oa_live_abc123...
# Access in code
const apiKey = process.env.ONEAPP_API_KEY;Create new keys periodically and revoke old ones. Set expiration dates on keys.
Only request the scopes you need. Avoid using admin scope unless absolutely necessary.
Don't commit keys to git, log them, or expose them in client-side code.
Check that your token/key is correct and not expired.
Your key doesn't have the required scope for this operation.
Ensure you're using the correct header format and the key hasn't been revoked.