Sandbox Environment

The sandbox is an isolated copy of the AlchemOS Positive platform for development and testing. All API behaviour is identical to production, but no real data is created and no real financial transactions occur.

Sandbox base URL

https://sandbox.api.alchemos.io/api/v1

Use alch_test_ prefixed API keys with this URL.

Accessing the sandbox

Log in to your AlchemOS Positive account
Click the environment switcher (top-right of the navigation bar): Production → Sandbox
The UI switches to sandbox mode — indicated by an amber "Sandbox" banner

Sandbox API keys are created under Settings → API Keys → Sandbox.

Sandbox data

The sandbox is pre-seeded with:

Sample organisations (two test tenants)
A library of sample emission entries (Scope 1, 2, 3) across various categories
Sample targets with milestone data
Sample offset projects with available credits
Sample certificates in different states

This data allows you to test all API endpoints immediately without needing to set up your own organisation data first.

Reset schedule: Sandbox data resets to the pre-seeded state every Sunday at 02:00 UTC. Any data you create during the week is wiped.

Sandbox-specific behaviours

Payments

Payment processing is simulated. Use the test card 4242 4242 4242 4242 (any expiry, any CVV) for all card payments. Bank transfers can be simulated via the sandbox API:

POST /api/v1/offsets/orders/{orderId}/simulate-payment

This endpoint is sandbox-only and does not exist in production.

Registry retirements

Offset retirements in the sandbox skip the real registry API call. The retirement status moves from submitted to confirmed automatically within 5 seconds, with a fake serial number range assigned.

Email delivery

Emails (invitation, certificate, scheduled reports) are captured in the sandbox inbox, visible at:

https://sandbox.alchemos.io/sandbox-inbox

No real emails are sent.

Webhooks

Webhooks fire normally in the sandbox. Use your test endpoint URL configured in Settings → Webhooks within the sandbox environment.

Testing error scenarios

The sandbox supports deliberate error injection via special request headers:

Header	Value	Effect
`X-Simulate-Error`	`rate_limit`	Forces a 429 response
`X-Simulate-Error`	`server_error`	Forces a 500 response
`X-Simulate-Error`	`slow_response`	Delays response by 8 seconds (timeout testing)
`X-Simulate-Error`	`validation_error`	Forces a 422 response

curl -H "X-Simulate-Error: rate_limit" \
  -H "Authorization: Bearer alch_test_xxxx" \
  https://sandbox.api.alchemos.io/api/v1/emissions

Differences from production

Feature	Production	Sandbox
Real data	✅	❌ (seeded + ephemeral)
Real payments	✅	❌ (simulated)
Real registry retirements	✅	❌ (mocked, 5s confirm)
Real email delivery	✅	❌ (inbox capture)
Rate limits	Plan limits	500 req/min (generous for testing)
Data reset	Never	Sundays 02:00 UTC
Error injection headers	❌	✅

Migrating from sandbox to production

Once your integration is working in sandbox:

Switch your API key from alch_test_ to alch_live_
Update the base URL from sandbox.api.alchemos.io to api.alchemos.io
Update your webhook endpoint URL in Settings → Webhooks (production environment)
Verify your error handling against production rate limits (lower than sandbox)