API keys

Key prefixes

Every Credicorp key is prefixed so its purpose and environment are unmistakable on sight. Treat the prefix as authoritative: a sk_live key moves real money; a sk_sandbox key never can.

Secret keys — sk_live / sk_sandbox

The full-power credential. A secret key plus your client_id mints OAuth tokens that can create applications, pull decisions and instruct payments. It must never appear in front-end code, a mobile binary, a public Git repo, a log line or a webhook payload. If a secret key is exposed, treat it as compromised and rotate it.

# sk_* is the client_secret in the OAuth exchange
curl -s https://hub.credicorp.co.uk/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=$CC_CLIENT_ID" \
  -d "client_secret=sk_live_8Kd2c9QmReHv…" \
  -d "scope=applications:write decisions:read"

Publishable keys — pk_live / pk_sandbox

Safe to embed in a browser or mobile app. A publishable key can only do front-end-safe things: initialise the hosted apply widget, tokenise an applicant's details before they reach your server, and start a PISP bank-selection screen. It cannot read applications, pull decisions or move money. There is nothing to protect — exposure is expected.

<script src="https://js.credicorp.co.uk/v1/apply.js"></script>
<script>
  const apply = Credicorp.apply("pk_live_3fa7Qe9mZ…");
  apply.mount("#apply-widget", { amountPence: 2500000, termMonths: 12 });
</script>

Webhook signing secrets — whsec

Issued per endpoint when you register a webhook. Credicorp signs every delivery with this secret so you can prove the payload came from us and wasn't tampered with. It is a verification secret, not a credential — it can't call the API. Keep it server-side and feed it to your signature check. Full verification recipe in Request signing roadmap.

# Register an endpoint → the response includes its whsec
{
  "id": "whk_5Tg1aB",
  "url": "https://yourapp.com/webhooks/credicorp",
  "events": ["decision.completed", "payment.settled"],
  "secret": "whsec_9mQ2…",
  "status": "active"
}

Environment binding

A key is welded to one environment for its whole life. There is no flag, header or parameter that crosses a sandbox key into production — the prefix is the boundary, and the API enforces it.

Secure storage

Secret keys (sk_*, whsec_*) are bearer credentials: whoever holds one can act as your project. Store them accordingly.

• Inject from a secrets manager — AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Doppler — at deploy time. Read them as environment variables; don't bake them into images.
• Never commit keys to source control. Add .env to .gitignore and ship a .env.example with placeholders. Credicorp keys are detected by GitHub secret scanning — a pushed live key is auto-reported to us and quarantined.
• Never log a full key. If you must log for support, log only the prefix and last four (sk_live_…Hv9k).
• Scope by service. Give each service its own project and key so you can rotate one without redeploying the world.
• Don't put secret keys in a browser, mobile app, CLI distributed to users, or front-end build. Anything a user can decompile is public — use a pk_* key there.

# .env  (git-ignored)
CC_CLIENT_ID=cc_client_8Kd2c9Qm
CC_SECRET_KEY=sk_live_8Kd2c9QmReHv…
CC_WEBHOOK_SECRET=whsec_9mQ2…

# .gitignore
.env
.env.*.local

Managing keys

Create, list and revoke keys from the developer dashboard, or programmatically with a token carrying partner:manage.

Zero-downtime rotation

Rolling a secret key issues a successor and opens an overlap window during which both keys authenticate. You move traffic, confirm, then retire the predecessor — no maintenance window, no failed requests.

curl -s -X POST https://hub.credicorp.co.uk/partner/v1/keys/key_7Hn3/roll \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "overlap_hours": 48 }'

# → 201 Created — new secret shown once
{
  "id": "key_9Lp4",
  "secret": "sk_live_NewSecretShownOnce…",
  "predecessor": "key_7Hn3",
  "predecessor_expires_at": "2026-07-01T09:00:00Z"
}

1. Roll — capture the new sk_live from the response (shown once).
2. Deploy the new key to your secrets manager and roll your fleet. The predecessor still works.
3. Verify the dashboard shows the new key in use and the predecessor idle.
4. Retire — let the predecessor lapse at predecessor_expires_at, or DELETE it early.

Revocation

Revocation is instant and irreversible. The moment a key is revoked, every new token request with it fails 401 key_revoked. Tokens already minted under that key remain valid until they expire (≤ 1 hour) — if you need to kill those too, revoke the outstanding tokens from the OAuth dashboard.

Next: verify that the webhook deliveries Credicorp signs with your whsec are genuine and untampered — see Request signing roadmap.