API Keys
API keys allow your applications and integrations to authenticate with the AlchemOS Positive REST API without using a user's password. Each key is scoped to specific permissions and can be rotated or revoked independently.
Creating an API key
- Go to Settings → API Keys → New Key
- Complete the key creation form:
| Field | Description |
|---|---|
| Name | Descriptive label (e.g. "Data warehouse export", "CI pipeline") |
| Expiry | Never / 30 days / 90 days / 1 year / Custom date |
| Permissions | Select the API scopes this key can access |
- Click Create Key
- Copy the key value — it is shown only once. Store it securely (password manager, secrets vault).
Permission scopes
| Scope | Access granted |
|---|---|
emissions:read |
Read emission entries and factors |
emissions:write |
Create and update emission entries |
reports:read |
Download reports |
reports:write |
Generate new reports |
offsets:read |
Read offset credits and retirements |
offsets:write |
Initiate purchases and retirements |
certificates:read |
Read certificates |
certificates:write |
Request and manage certificates |
settings:read |
Read organisation settings, locations, users |
settings:write |
Modify organisation settings |
admin |
Full access (use with caution; restrict to trusted systems) |
Assign the minimum scopes required for the integration. This limits exposure if the key is ever compromised.
Using an API key
Include the key in the Authorization header of every request:
GET /api/v1/emissions HTTP/1.1
Host: api.alchemos.io
Authorization: Bearer alch_live_xxxxxxxxxxxxxxxxxxxx
API keys are prefixed alch_live_ (production) or alch_test_ (sandbox environment).
Managing existing keys
Go to Settings → API Keys to see all keys:
| Column | Description |
|---|---|
| Name | Key label |
| Created | Date created and by whom |
| Last used | Date/time of most recent authenticated request |
| Expiry | Expiry date or "Never" |
| Status | Active / Expired / Revoked |
Rotating a key
- Click the key → Rotate
- A new key value is generated immediately
- The old value is invalidated — update all systems using the key before completing the rotation
Revoking a key
Click Revoke to permanently invalidate the key. This cannot be undone. The key's request history is retained in the audit log.
Key security best practices
- Never commit API keys to source control (git). Use environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault).
- Set expiry dates for non-critical integrations.
- Rotate keys when a developer with access leaves the team.
- Use separate keys per system (not one shared key for everything).
- Audit Last Used dates regularly; revoke keys that haven't been used in 90+ days.
Sandbox keys
Use sandbox keys (alch_test_ prefix) during development. Sandbox environments are isolated; no real data or financial transactions occur. Create sandbox keys separately in Settings → API Keys → Sandbox.
Rate limits
| Plan | Requests / minute | Requests / day |
|---|---|---|
| Standard | 60 | 5,000 |
| Pro | 300 | 50,000 |
| Enterprise | 1,000 | Unlimited |
Rate limit headers are returned on every response:
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1730000000