OAuth 2.0

Client-credentials grant

Exchange your project's client_id and client_secret for a short-lived bearer token. Request only the scopes the call needs — a token minted for mcp.read alone cannot reach account.read data. The token endpoint accepts application/x-www-form-urlencoded or HTTP Basic for the credentials.

curl -s https://hub.credicorp.co.uk/partner/v1/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=$CC_CLIENT_ID" \
  -d "client_secret=$CC_CLIENT_SECRET" \
  -d "scope=mcp.read account.read"

import { Credit Corp } from "@credicorp/sdk";

// The SDK fetches, caches and refreshes the token for you.
const cc = new Credit Corp({
  clientId: process.env.CC_CLIENT_ID,
  clientSecret: process.env.CC_CLIENT_SECRET,
  scopes: ["mcp.read", "account.read"],
});

const token = await cc.auth.accessToken();

use Credit Corp\Client;

// Token acquisition and refresh are handled by the client.
$cc = new Client([
    'client_id'     => getenv('CC_CLIENT_ID'),
    'client_secret' => getenv('CC_CLIENT_SECRET'),
    'scopes'        => ['mcp.read', 'account.read'],
]);

$token = $cc->auth()->accessToken();

Request parameters

Token response

# → 200 OK
{
  "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6Imh1Yi1vYXV0aC1lZDI1NTE5In0…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "mcp.read account.read"
}

The access token is a signed EdDSA JWT (Ed25519, key id hub-oauth-ed25519). You don't need to parse it — treat it as an opaque bearer string — but if you do, the public keys are published at the JWKS endpoint below so you can verify iss, aud, exp and scope locally.

Scope catalogue

The partner OAuth plane is read-only. All four scopes use the .read dot form (distinct from the internal colon form) so they can never be confused with write grants. A request that touches data outside its token's scope is rejected with 403 insufficient_scope and a WWW-Authenticate header naming the scope required.

Token caching

Access tokens are valid for one hour (expires_in: 3600). Cache and reuse them. Minting a fresh token on every API call is the most common integration mistake — it doubles your request volume and will trip the 10 req/s limit on the token endpoint.

• Store the token in process memory, or in Redis / Memcached if you run multiple instances, keyed by client_id + scope-set.
• Refresh proactively at ~90% of lifetime (roughly 60 seconds before exp) so an in-flight request never races expiry.
• On a 401 invalid_token, refresh once and retry the original request a single time.

let cached = { token: null, exp: 0 };

async function getToken() {
  const now = Date.now() / 1000;
  if (cached.token && now < cached.exp - 60) return cached.token;   // reuse

  const r = await fetch("https://hub.credicorp.co.uk/partner/v1/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: process.env.CC_CLIENT_ID,
      client_secret: process.env.CC_CLIENT_SECRET,
      scope: "mcp.read account.read",
    }),
  });
  const j = await r.json();
  cached = { token: j.access_token, exp: now + j.expires_in };
  return cached.token;
}

Rotating client secrets

The authorization server supports two live secrets per client so you can rotate with zero downtime. The roll never requires a maintenance window.

1. Generate a second secret from the developer dashboard (or POST /oauth/clients/{id}/secrets). Both old and new now authenticate.
2. Deploy the new secret to your environment — rolling restart, blue/green, whatever you run. Old instances keep working on the old secret.
3. Verify traffic is minting tokens with the new secret (the dashboard shows last-used timestamps per secret).
4. Revoke the old secret. Any token already issued under it stays valid until it expires; no new tokens can be minted with it.

Authorization-server discovery

Never hard-code endpoint URLs. Fetch the RFC 8414 authorization-server metadata document at start-up and cache the endpoint addresses. The document is published at:

{
  "issuer": "https://hub.credicorp.co.uk",
  "token_endpoint": "https://hub.credicorp.co.uk/partner/v1/oauth/token",
  "jwks_uri": "https://hub.credicorp.co.uk/partner/v1/oauth/jwks",
  "introspection_endpoint": "https://hub.credicorp.co.uk/partner/v1/oauth/introspect",
  "grant_types_supported": ["client_credentials"],
  "response_types_supported": [],
  "scopes_supported": ["mcp.read", "account.read", "ops.read", "owner.read"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post"],
  "id_token_signing_alg_values_supported": ["EdDSA"],
  "service_documentation": "https://hub.credicorp.co.uk/partner/v1/auth.md"
}

Access tokens are EdDSA JWTs (Ed25519, kid=hub-oauth-ed25519). Verify the signature against the JWKS published at jwks_uri and check iss, aud, exp and scope. The partner plane supports only client_credentials — there is no authorization-code or refresh-token flow.

Authorization-server endpoints

Token errors

The token endpoint returns standard OAuth 2.0 errors. Treat invalid_client as a hard failure — do not retry with the same credentials.

Most integrations only need client-credentials. If you're calling from a browser, mobile app or webhook receiver instead of your own backend, read API keys for publishable keys and webhook secrets, and Request signing to verify webhook deliveries.