79 lines
2.8 KiB
Plaintext
79 lines
2.8 KiB
Plaintext
---
|
|
title: Authentication
|
|
description: Learn how to authenticate with the OpenPanel API using client credentials.
|
|
---
|
|
|
|
## Authentication
|
|
|
|
To authenticate with the OpenPanel API, you need to use your `clientId` and `clientSecret`. Different API endpoints may require different access levels:
|
|
|
|
- **Track API**: Default client works with `write` mode
|
|
- **Export API**: Requires `read` or `root` mode
|
|
- **Insights API**: Requires `read` or `root` mode
|
|
- **Manage API**: Requires `root` mode only
|
|
|
|
The default client (created with a project) has `write` mode and does not have access to the Export, Insights, or Manage APIs. You'll need to create additional clients with appropriate access levels.
|
|
|
|
## Headers
|
|
|
|
Include the following headers with your API requests:
|
|
|
|
- `openpanel-client-id`: Your OpenPanel client ID
|
|
- `openpanel-client-secret`: Your OpenPanel client secret
|
|
|
|
## Example
|
|
|
|
```bash
|
|
curl 'https://api.openpanel.dev/insights/{projectId}/metrics' \
|
|
-H 'openpanel-client-id: YOUR_CLIENT_ID' \
|
|
-H 'openpanel-client-secret: YOUR_CLIENT_SECRET'
|
|
```
|
|
|
|
## Security Best Practices
|
|
|
|
1. **Store credentials securely**: Never expose your `clientId` and `clientSecret` in client-side code
|
|
2. **Use HTTPS**: Always use HTTPS to ensure secure communication
|
|
3. **Rotate credentials**: Regularly rotate your API credentials
|
|
4. **Limit access**: Use the minimum required access level for your use case
|
|
|
|
## Error Responses
|
|
|
|
If authentication fails, you'll receive a `401 Unauthorized` response:
|
|
|
|
```json
|
|
{
|
|
"error": "Unauthorized",
|
|
"message": "Invalid client credentials"
|
|
}
|
|
```
|
|
|
|
Common authentication errors:
|
|
- Invalid client ID or secret
|
|
- Client doesn't have required permissions (e.g., trying to access Manage API with a non-root client)
|
|
- Malformed client ID (must be a valid UUIDv4)
|
|
- Client type mismatch (e.g., `write` client trying to access Export API)
|
|
|
|
## Client Types
|
|
|
|
OpenPanel supports three client types with different access levels:
|
|
|
|
| Type | Description | Access |
|
|
|------|-------------|--------|
|
|
| `write` | Write access | Track API only |
|
|
| `read` | Read-only access | Export API, Insights API |
|
|
| `root` | Full access | All APIs including Manage API |
|
|
|
|
**Note**: Root clients have organization-wide access and can manage all resources. Use root clients carefully and store their credentials securely.
|
|
|
|
## Rate Limiting
|
|
|
|
The API implements rate limiting to prevent abuse. Rate limits vary by endpoint:
|
|
|
|
- **Track API**: Higher limits for [event tracking](/features/event-tracking)
|
|
- **Export/Insights APIs**: 100 requests per 10 seconds
|
|
- **Manage API**: 20 requests per 10 seconds
|
|
|
|
If you exceed the rate limit, you'll receive a `429 Too Many Requests` response. Implement exponential backoff for retries.
|
|
|
|
Remember to replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with your actual OpenPanel API credentials.
|