Authentication
Everything about API keys, rate limits, and security for the Northly API.
Bearer Token Authentication
All API requests are authenticated using Bearer tokens.
Send your API key as a Bearer token in the Authorization header of every request. All requests must be made over HTTPS.
bash
curl -X GET "https://api.northlyapp.com/v1/objectives" \
-H "Authorization: Bearer nly_live_abc123def456..."API Key Management
Create and manage your API keys securely.
- Create API keys in the Northly settings under "API Keys".
- Each key can be given a name and optional permissions.
- Revoke a key immediately if it has been compromised.
- API access requires at least the Business plan.
Rate Limits
The API is limited to a certain number of requests per hour.
| Plan | Limit |
|---|---|
| Business | 1,000 requests/hour |
| Enterprise | 5,000 requests/hour |
Rate limit information is returned in the response headers:
http
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 1709985600Error Codes
The API uses standard HTTP status codes.
| Code | Name | Description |
|---|---|---|
400 | Bad Request | The request was invalid or malformed. |
401 | Unauthorized | Missing or invalid API key. |
403 | Forbidden | No permission for this action. |
404 | Not Found | The requested resource was not found. |
422 | Unprocessable Entity | Validation error in the input data. |
429 | Too Many Requests | Rate limit exceeded. Try again later. |
500 | Internal Server Error | An unexpected error occurred. |
400Bad RequestThe request was invalid or malformed.
401UnauthorizedMissing or invalid API key.
403ForbiddenNo permission for this action.
404Not FoundThe requested resource was not found.
422Unprocessable EntityValidation error in the input data.
429Too Many RequestsRate limit exceeded. Try again later.
500Internal Server ErrorAn unexpected error occurred.
Example error response:
json
{
"error": {
"code": "unauthorized",
"message": "Invalid or expired API key",
"status": 401
}
}Security Best Practices
Best practices for securely handling API keys.
- Never store API keys in source code or public repositories.
- Use environment variables or a secret manager.
- Rotate API keys regularly.
- Use a separate API key for each service.
- All API requests must be made over HTTPS – HTTP is rejected.