Environments and test mode
Build against a sandbox copy of your organisation with a test key, where no messages are sent and nothing is billed, then switch to a live key.
This is a published preview. Names and fields may still change before general availability; changes will be listed in the changelog.
Agoo has two modes, live and test, behind one base URL:
https://api.agoo.ardent.africa/v1The key you send decides the mode. A key containing _live_ works on your real organisation. A key containing _test_ works on a separate sandbox copy of it. There's no separate test host to configure, so the only thing that changes when you go live is the key.
| Key prefix | Mode |
|---|---|
agoo_sk_live_…, agoo_pk_live_… | Live |
agoo_sk_test_…, agoo_pk_test_… | Test |
How test mode differs
| Live mode | Test mode | |
|---|---|---|
| Data | Your real organisation | A separate sandbox copy of your organisation |
| SMS, WhatsApp, email | Sent to real people; counts towards your allowance and wallet | Never sent. Each message appears in the console's test outbox |
| Billing | Usage counts towards your plan | Nothing is billed or counted |
| Webhooks | Live endpoints receive events with "livemode": true | Test endpoints receive events with "livemode": false |
| Rate limit | Depends on your plan (see rate limits) | 100 requests a minute on every plan |
| Plan | Free and Starter have no live API; Growth has webhooks; Pro and Enterprise have the full API | Every endpoint works on every plan |
Test mode is on every plan, including Free, so you can build and test an integration before you upgrade.
What's in the sandbox
The sandbox starts as a copy of your organisation's set-up: its sites, gates, people and forms. Everything you create with a test key, such as visits, visitors, bookings, deliveries and webhook endpoints, exists only in the sandbox.
Live and test data never mix:
- Objects created in test mode never appear in live mode, and live objects never appear in test mode.
- IDs belong to one mode. Look IDs up with the key you'll use them with. A live ID sent with a test key returns
not_found. - Webhook endpoints belong to one mode. Create your live endpoints again with a live key when you go live; each gets a new signing secret.
- Idempotency keys and rate limits are counted separately for each mode.
To check which mode a key works in, call GET/organisation and read livemode. Every event also carries livemode, so a handler shared by both modes can tell them apart.
See the messages Agoo would have sent
When something in test mode would send an SMS, a WhatsApp message or an email, such as a QR pass, a host notification or an "I'm safe" link, Agoo puts the message in the console's test outbox instead. Open it to check the wording, the links and which channel was used, without messaging anyone.
Use fictional people in test mode
Test mode doesn't send messages, but it does store what you send it. Use made-up names and the example numbers in these docs, not real visitors' details.
Drive visits through their life
In test mode, you move test visits along with the API. It's also the quickest way to make each webhook event happen:
- POST/visits fires
visit.createdandpass.sent. - POST/visits/{visit_id}/check-in fires
visit.checked_in, orvisit.approval_requestedif the site needs host approval. - POST/visits/{visit_id}/approve fires
visit.approvedandvisit.checked_infor a visitor who has arrived. Approving a pre-registration before the visitor arrives firesvisit.approved, thenpass.sent, and leaves the visitexpected. - POST/visits/{visit_id}/check-out fires
visit.checked_out.
Go live
Check your plan
Live API calls need Pro or Enterprise, or Growth for webhook endpoints and events. A live call above your plan returns plan_required.
Create a live key with the same scopes
In Console → Developers → API keys, create a live key with the scopes your test key has, and store it where your production code reads it.
Replace test IDs with live ones
Any site, gate, person or booking type IDs you stored from test mode won't work live. Look them up again with the live key.
Create your live webhook endpoints
Register each endpoint again with the live key and store the new signing secrets. Keep your test endpoints for staging.
Plan for the live rate limit
Check the RateLimit-* headers on your first live calls; your plan's limit applies from now on.