Authentication

The AlchemOS Positive API uses Bearer token authentication. Every request must include a valid API key in the Authorization header.

Obtaining an API key

Generate API keys in the platform under Settings → API Keys. See the API Keys user guide for full instructions.

Including the key in requests

GET /api/v1/emissions HTTP/1.1
Host: api.alchemos.io
Authorization: Bearer alch_live_xxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

API keys must be passed in the Authorization header. Query string and cookie-based auth are not supported.

Key prefixes

Prefix	Environment
`alch_live_`	Production — real data and transactions
`alch_test_`	Sandbox — isolated test environment

Always use alch_test_ keys during development to avoid accidentally modifying production data.

OAuth 2.0 (for user-context requests)

For applications where actions should be attributed to a specific user (not a service account), use the OAuth 2.0 authorization code flow:

Step 1 — Redirect to authorisation endpoint

GET https://id.alchemos.io/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=emissions:read reports:read
  &state=random_csrf_token

Step 2 — Exchange code for tokens

POST https://id.alchemos.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_FROM_REDIRECT
&redirect_uri=https://yourapp.com/callback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_xxxxxxxxxxxx",
  "scope": "emissions:read reports:read"
}

Step 3 — Use the access token

Same as API key — include in the Authorization: Bearer header.

Access tokens expire after 1 hour. Use the refresh token to obtain a new access token:

POST https://id.alchemos.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=rt_xxxxxxxxxxxx
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Permission scopes

Scope	Description
`emissions:read`	Read emission entries
`emissions:write`	Create and update emission entries
`reports:read`	Read and download reports
`reports:write`	Generate 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 settings and users
`settings:write`	Modify settings
`admin`	All scopes

Authentication errors

HTTP Code	Error code	Cause
`401`	`INVALID_TOKEN`	Key is malformed, revoked or expired
`401`	`TOKEN_MISSING`	No Authorization header present
`403`	`INSUFFICIENT_SCOPE`	Key doesn't have the required scope for this endpoint
`403`	`IP_RESTRICTED`	Request from an IP not on the allowlist

IP allowlisting (Enterprise)

Enterprise plans can restrict API keys to specific source IP ranges. Configure in Settings → API Keys → → IP Restriction.