Skip to main content
The Partner API authenticates with bearer tokens. Pass the token in the Authorization header on every request:
Same shape as Stripe, Plaid, and most modern payment APIs.

​
Token format

API keys are ULID-encoded with an environment prefix. A sandbox key returns 401 against production endpoints. A live key returns 401 against sandbox endpoints. No accidental cross-environment usage.

​
Getting a key

From the Partner Portal at https://partners.guild.com.ng/keys. The full secret is shown exactly once at creation; copy it to your secrets manager immediately. Keys are issued only after partner onboarding completes (regulatory review, contractual signing). See Partner Portal → API keys for the onboarding flow.

​
Scopes

Each key has a set of scopes. The default is unscoped (full Partner API access). Recommended practice: create scoped keys for principle-of-least-privilege. A key without the required scope returns 403 scope_insufficient.

​
IP allowlisting

Optional but recommended for production keys. Configure from https://partners.guild.com.ng/keys/:keyId/allowlist.
  • Up to 32 entries per key.
  • IPv4 and IPv6 supported.
  • CIDR notation accepted (192.0.2.0/24).
A request from an IP not in the allowlist returns 401 ip_not_allowed.

​
What happens when a request arrives

The auth check runs in this order:
1

Extract bearer token

From Authorization header. Missing → 401 missing_auth.
2

Hash and look up

We store an Argon2id hash of the secret, never the raw value. Lookup hit → continue. Miss → 401 invalid_auth.
3

Status check

Key must be ACTIVE. Revoked, suspended, expired → 401 invalid_auth.
4

IP allowlist

If configured, source IP must match. Otherwise → 401 ip_not_allowed.
5

Scope check

Requested operation must be in the key’s scope set. Otherwise → 403 scope_insufficient.
6

Rate limit

Per-key token bucket. Exceeded → 429 rate_limited with Retry-After header.
7

Consent check (if applicable)

For snapshot reads, the X-Guild-Consent-Token header must reference an active consent for the target user. Otherwise → 403 consent_missing / consent_revoked / consent_expired.
Each rejection writes a row to the partner_api_audit log so you can debug from the dashboard.

​
Rotating keys

Recommended every 90 days. Rotation procedure:
1

Generate a new key

Same scopes and allowlist as the key you’re replacing.
2

Roll out gradually

Deploy the new key to a single instance of your service. Verify it works. Then roll out to the rest.
3

Watch usage drop to zero on the old key

Each key shows last-seen timestamp and request count. Wait until the old key has been quiet for at least an hour.
4

Revoke the old key

From the dashboard. Immediate effect; any straggling request returns 401.

​
Compromise response

If a key leaks (committed to a public repo, sent in plaintext email, observed in unusual traffic), revoke immediately with reason=compromised:
We:
  • Mark the key revoked immediately.
  • Open an incident on our side.
  • Scan our logs for unusual usage patterns.
  • Notify you within an hour with what we found.
Generate a replacement key and rotate your infrastructure to use it.

​
Webhook authentication

Webhook subscriptions have their own secrets, distinct from API keys. We use the webhook secret to sign outbound webhooks; you verify on receipt. Detail at Webhooks.

Errors

What every auth-related error code means.

Snapshots

The endpoint you’ll use most.