Authentication

Every request to the Agoo API carries a bearer token in the Authorization header:

GET /v1/sites HTTP/1.1
Host: api.agoo.ardent.africa
Authorization: Bearer agoo_sk_test_…

The token is one of two things:

Agoo only accepts credentials in the Authorization header. There's no query-string or cookie alternative, so keys never end up in URLs, server logs or browser history.

API keysCopy Anchor Link

Secret and publishable keysCopy Anchor Link

A secret key can read and change your organisation's data, including personal data about visitors and staff. Treat it like a password: it belongs on a server, never in a web page, a mobile app or a kiosk.

A publishable key is safe to ship in client code because it can only do what a member of the public can already do on your booking and pre-registration pages:

• GET/visit-types and GET/visit-types/{visit_type}, only for visit types that are turned on and open for pre-registration, each with its public_form: the questions asked of the visitor, never the fields your staff fill in
• POST/visits, which creates a pre-registration (source: "pre_registration") for a visit type open for pre-registration, with only the fields in its public_form
• GET/booking-types, public booking types only, each with its public_form of intake questions
• GET/booking-types/{btype_id}/availability, for public booking types
• POST/bookings, for public booking types, with only the fields in their public_form

Any other call with a publishable key returns forbidden, including GET /forms (full forms contain the fields your staff fill in) and GET /people (your staff directory is never readable from a web page). A visit type that isn't open for pre-registration returns not_found from GET /visit-types/{visit_type} and validation_failed from POST /visits. Admins open a type for pre-registration in Console → Settings → Forms (Forms and fields).

Live and test keysCopy Anchor Link

The key decides the mode. Live and test mode share one base URL, https://api.agoo.ardent.africa/v1. A _test_ key works on a separate sandbox copy of your organisation where no SMS, WhatsApp or email is sent and nothing is billed. See Environments and test mode.

Create a keyCopy Anchor Link

Owners and Admins create keys.

You can't change a key's scopes after you create it. To give an integration more or fewer permissions, create a new key and rotate to it.

Store keys safelyCopy Anchor Link

• Keep keys in environment variables or a secret manager, never in source code. Agoo's prefixes (agoo_sk_live_ and friends) make leaked keys easy for secret scanners to spot.
• Give each integration its own key, so you can see what each one does in the audit trail and revoke one without breaking the others.
• Give each key the fewest scopes it needs. A payroll export needs attendance:read, not people:write.
• Never log the Authorization header. If you log requests, log the Agoo-Request-Id response header instead.
• Never send a secret key to a browser, a mobile app or a kiosk. If a page needs to create bookings, use a publishable key; if it needs more, call your own server and let your server call Agoo.

Rotate a keyCopy Anchor Link

Rotate keys when someone who had access leaves, on your regular schedule, or straight away if you think a key has leaked.

Revoke a keyCopy Anchor Link

Revoking takes effect at once: every request with that key returns unauthorized, and revoking can't be undone. If a key leaks, revoke it first and create the replacement second; a few minutes of failed calls are better than an open door. Revocations are recorded in the audit trail.

IP allow-lists (Enterprise)Copy Anchor Link

Enterprise organisations can limit API access to the IP ranges they list. A request from any other address returns forbidden, even with a valid key.

OAuth 2.1 for appsCopy Anchor Link

Use OAuth when you build an app that other organisations connect to their Agoo, or when a person connects an MCP client such as an AI assistant. The app never sees anyone's password or API key: each organisation grants it a token, limited to the scopes it asked for, that the organisation can revoke at any time.

Agoo follows OAuth 2.1: the authorization code flow with PKCE (S256 only), exact redirect URI matching, short-lived access tokens and refresh tokens that rotate on every use. The implicit and password grants aren't supported.

The metadata document lists everything else, including the revocation endpoint, the client authentication methods the token endpoint accepts and client_id_metadata_document_supported: true, which tells MCP clients they can register with a Client ID Metadata Document. Read those values from it rather than hard-coding them.

Register your appCopy Anchor Link

Register your app in Console → Developers on your own Agoo organisation (Pro or Enterprise). You get a client ID and, for apps that run on a server, a client secret, shown once.

• Redirect URIs must match exactly, including the path and any trailing slash. Use HTTPS; http://localhost is allowed while you develop.
• Confidential clients run on a server and keep a client secret. Public clients, such as desktop and mobile apps, have no secret and rely on PKCE alone.
• MCP clients register themselves, so you don't need to do anything. See How MCP clients register.

How MCP clients registerCopy Anchor Link

AI assistants and other MCP clients connect to many servers they have no prior relationship with, so they identify themselves when they first connect. Agoo supports the two ways the MCP authorization specification (revision 2026-07-28) describes:

A metadata document needs at least client_id, client_name and redirect_uris. Agoo caches it as its HTTP cache headers allow, shows the client's name and the redirect address's host name on the consent screen, and warns when the only redirect addresses are on localhost. Not every MCP client supports metadata documents yet; those that don't use dynamic client registration, which works the same for you. Either way, an admin approves the client for your organisation before it gets a token. See Connect an MCP client.

Walk through the authorization code flowCopy Anchor Link

The example below is Coastline Consult's CRM connecting to Volta Bank's Agoo, so it can invite Coastline's consultants as visitors.

import { createHash, randomBytes } from "node:crypto"

export function createPkce() {
  const codeVerifier = randomBytes(32).toString("base64url") // 43 characters
  const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url")
  const state = randomBytes(16).toString("base64url")
  return { codeVerifier, codeChallenge, state }
}

GET https://app.agoo.ardent.africa/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fcrm.coastline.example%2Fagoo%2Fcallback
  &scope=visits%3Aread%20visits%3Awrite%20people%3Aread
  &state=kN3vQ8tWzR1yLp6s
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

GET https://crm.coastline.example/agoo/callback?code=AUTHORIZATION_CODE&state=kN3vQ8tWzR1yLp6s

curl https://api.agoo.ardent.africa/oauth/token \
  -u "$AGOO_CLIENT_ID:$AGOO_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$AUTHORIZATION_CODE" \
  -d redirect_uri=https://crm.coastline.example/agoo/callback \
  -d code_verifier="$CODE_VERIFIER"

{
  "access_token": "<access token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "<refresh token>",
  "scope": "visits:read visits:write people:read"
}

curl https://api.agoo.ardent.africa/v1/visits?status=expected \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Refresh tokensCopy Anchor Link

Access tokens last 1 hour. Before one expires, or when a call returns unauthorized, get a new one:

curl https://api.agoo.ardent.africa/oauth/token \
  -u "$AGOO_CLIENT_ID:$AGOO_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"

Refresh tokens rotate: every refresh returns a new refresh token, and the one you sent stops working. Save the new one before you use the new access token. If an old refresh token is ever presented again, Agoo treats it as stolen and revokes the whole grant, so the person has to connect again. Two servers refreshing the same grant at once can trigger this, so refresh in one place, under a lock.

Errors from the token endpoint follow OAuth (RFC 6749), not problem details: for example { "error": "invalid_grant" } when a code or refresh token is expired, used or revoked. When you get invalid_grant on a refresh, send the person through the authorization flow again.

RevocationCopy Anchor Link

• Your app can revoke a token it no longer needs, for example when a customer disconnects Agoo in your product. Post it to the revocation_endpoint from the server metadata (RFC 7009). Revoking a refresh token also revokes the access tokens issued from it.
• An organisation's admins can revoke your app at any time from the console. Its tokens stop working at once and further calls return unauthorized; your app should show the customer that the connection has ended.

Choosing between keys and OAuthCopy Anchor Link

ScopesCopy Anchor Link

Scopes apply to API keys and OAuth tokens alike. Enterprise organisations can agree custom scopes with Ardent.

Each endpoint in the API reference lists the scope it needs.

A write scope lets you read the objects it creates or changes in the response. For example, a key with only people:write gets the person back from POST /people and PATCH /people/{person_id}, and a key with only visits:write gets the visit back from POST /visits and the visit actions. It doesn't let you list or fetch those objects: that still needs the read scope.

RelatedCopy Anchor Link