Authentication

Pientegra External API uses the standard HTTP Authorization header for request authentication:

Authorization: Bearer <raw-api-key>

The raw key is visible only at creation time. Pientegra does not store the raw key; lookup is performed with an HMAC-SHA256 hash. If you lose the key, it cannot be retrieved and a new key must be generated.

Key format

Raw keys use this format:

sk_live_<site-slug>_<secret>

<secret> is the base64url encoding of 32 random bytes. Your integration code should not try to parse the key; send the full string as the Bearer credential.

Request example

curl "$PIENTEGRA_API_BASE/external/intents/01927b3c-9c1f-7a3a-9c4f-8a3e1f8b1c00" \
  -H "Authorization: Bearer $PIENTEGRA_API_KEY"

const response = await fetch(`${process.env.PIENTEGRA_API_BASE}/external/withdrawals`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PIENTEGRA_API_KEY!}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    externalUserId: 'user-12345',
    amount: '250000',
    currency: 'TRY',
    targetIban: 'TR320010009999901234567890',
    targetHolderName: 'Alex Morgan',
  }),
});

Secret handling

• Store the API key only in a server-side runtime.
• Do not place it in a browser bundle, mobile app, git repository, crash log, or analytics payload.
• Use a secret manager in production. The minimum acceptable setup is .env with restrictive file permissions.
• If you suspect a key leak, rotate the current key and revoke the old key after the new key is deployed.
• Use a separate key for each site. If one site is compromised, the blast radius does not extend to other sites.

Failure modes

Authentication failures are not resolved by retrying. Check the key, site status, and environment configuration.

Difference from webhook auth

Authorization is used only when the partner site sends requests to the Pientegra API. Webhooks sent by Pientegra do not use the API key; they carry an HMAC-SHA256 signature created with the per-site webhook secret.