Skip to main content
Authentication for the Partner API is a bearer token. You pass it as an Authorization: Bearer <key> header on every request. Simple, standard, and the same shape as Stripe’s or Plaid’s. The interesting parts are how you get the key, how to scope it, and how to rotate it without dropping production traffic.

​
Getting your first key

1

Sign up for the Partner Portal

partners.guild.com.ng/sign-up. Use your work email. We send a verification link. Click it, set up your organisation profile (legal name, regulator, primary contact).
2

Wait for approval

A real human at Guild reviews your application. We check your regulatory standing (if you’re a deposit-taking institution, we want to see your CBN licence; if you’re a non-bank lender, we ask for your business registration and a sample of an underwriting policy document). This typically takes 24-72 hours.
3

Generate keys

Once approved, partners.guild.com.ng/keys shows you the key management panel. You can generate keys for sandbox and production environments. The full secret is shown exactly once at creation — copy and store it securely.
The key prefix tells you the environment at a glance: Each key is a ULID-encoded secret. Length: 56 characters including prefix.

​
Using a key

Every request includes the bearer token:
The X-Guild-Consent-Token header is the consent reference for this specific user. See Consent.

​
Key scoping

When you generate a key, you can scope it. The default is unscoped (full Partner API access). You can narrow it for principle-of-least-privilege: Scope-restricted keys reduce blast radius if a key leaks. Most integrations create one read:snapshots key for their underwriting service and one write:disbursements key for their loan-fulfilment service.

​
IP allowlisting

Optional but recommended for production keys. partners.guild.com.ng/keys/:keyId/allowlist. Add the IP addresses or CIDR ranges that your backend uses. Requests from any other IP fail with 401, even with a valid key. We support IPv4 and IPv6. CIDR notation accepted (192.0.2.0/24). Up to 32 entries per key. If your infrastructure is on a cloud provider where your egress IP can change (e.g., AWS Lambda without a NAT gateway), don’t use IP allowlisting. Most production deployments have stable egress IPs and benefit from this layer.

​
Rotation

Keys should be rotated periodically. We recommend every 90 days; we won’t force it at v1, but we’ll surface a soft warning in the dashboard after 180 days of use. Rotation pattern:
1

Generate a new key

partners.guild.com.ng/keys/new. Same scopes, same allowlist as the key you’re replacing.
2

Update one service at a time

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

Watch the old key's usage drop to zero

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

Revoke the old key

partners.guild.com.ng/keys/:keyId/revoke. The key becomes immediately invalid; any request still using it fails with 401.
If you accidentally revoke the wrong key, generate a fresh one — you cannot un-revoke.

​
Compromise

If you suspect a key has leaked (committed to a public repo, sent in an unencrypted email, etc.), revoke it immediately: partners.guild.com.ng/keys/:keyId/revoke?reason=compromised. The reason=compromised flag opens an incident on our side too. We scan our logs for activity from the key against unusual IPs or patterns and notify you within an hour. Replace with a new key after revoking.

​
What happens when a request comes in

Behind the scenes, every request runs through the same auth check.
1

Extract the bearer token

From the Authorization header. If missing, return 401 with error_code: missing_auth.
2

Look up the key

Hashed-key lookup against our partner_api_keys table. We never store the raw secret — only an Argon2id hash. If no match, 401 with error_code: invalid_auth.
3

Check the key's status

Must be ACTIVE. Revoked, suspended, or expired keys fail.
4

Check IP allowlist

If allowlisting is on, the source IP must match. Otherwise 401 with error_code: ip_not_allowed.
5

Check the scope

The requested operation must match one of the key’s scopes. Otherwise 403 with error_code: scope_insufficient.
6

Check rate limit

Per-key token bucket. If exceeded, 429 with Retry-After header. See Rate limits.
7

For consent-required operations

Validate the X-Guild-Consent-Token header. The token must match an active consent record for the user being read and the partner holding the key. Otherwise 403 with error_code: consent_missing or consent_revoked.
8

Execute

All checks passed. The request runs.
Each rejection writes a row to our partner_api_audit table — your dashboard surfaces them so you can debug auth issues.

​
Test keys

Sandbox keys (gld_sandbox_*) work against api.sandbox.guild.com.ng. They cannot be used against production. They never charge real money. The users in sandbox are seeded synthetics — Musa, Mama Bisi, Engr. Adekunle, plus a hundred others with varied signal patterns. Most partners develop entirely against sandbox first, get our acceptance walkthrough, then flip a flag in their config to production.

​
Where to keep your keys

Standard advice, but worth restating:
  • Environment variables on your backend, not in source code.
  • Secrets manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Doppler) for production.
  • Never in client-side code, mobile apps, or anywhere that ships to the user.
  • Never in browser dev tools or shell history (use read with no echo in your CI).
If we detect requests from an obvious public host (e.g., the key shows up in a request from a residential IP that doesn’t match your allowlist), we’ll proactively suspend and notify.

​
Next

Consent

The other piece of the authentication picture — the per-user permission model.

Snapshots

The data you read with the keys.