Skip to main content

​
Authentication

Every request must be authenticated. This takes seconds to set up. Two separate authentication layers exist:
LayerWhoHow
ConsoleYou (the merchant)Email + password at console.palpluss.com
Developer APIYour applicationHTTP Basic Auth with an API key
Your application never uses your console password. It uses an API key you generate inside the console.

​
Step 1 — Create your account

Register at console.palpluss.com. After email verification and KYC approval your account is active.
KYC is required before initiating live STK Push or B2C transactions. You can generate API keys and test immediately after registration.

​
Step 2 — Generate an API key

  1. Log in to console.palpluss.com
  2. Go to Settings → API Keys
  3. Click Create API Key, name it, and select the required scopes
  4. Copy the key — it is shown only once
pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Store your API key in environment variables or a secrets manager — never in source code or version control. Revoke and reissue immediately if compromised.

​
Step 3 — Authenticate requests

Set your API key as the Basic Auth username. Leave the password empty. 
Authorization: Basic <base64(YOUR_API_KEY:)>
Note the trailing colon — it encodes an empty password. Most HTTP clients handle this automatically. 
curl https://api.palpluss.com/v1/wallets/service/balance \
  -u "pk_live_xxxxxxxxxxxxxxxxxxxx:"

​
How it works

Your server                  PalPluss API
─────────                    ────────────
  Request + Authorization header
────────────────────────────────────►
                                         Decode base64
                                         Lookup API key
                                         Verify account active
                                         Check key scopes
  200 OK / 401 Unauthorized
◄────────────────────────────────────
  1. Send Authorization: Basic <base64(key:)> on every request
  2. PalPluss decodes the header and looks up the key
  3. Valid key + active account → request proceeds
  4. Invalid, revoked, or suspended → 401

​
API key scopes

ScopeWhat it allows
payments:writeInitiate STK Push payments
b2c:writeSend B2C payouts
transactions:readList and retrieve transactions
wallets:readRead wallet balances
wallets:writeTop up service wallet
channels:writeCreate, update, and delete payment channels
Use the minimum scopes your integration needs.

​
Authentication errors

HTTPCodeReason
401INVALID_API_KEYKey not found, revoked, or Authorization header is malformed
401TENANT_INACTIVEAccount linked to this key is suspended
403INSUFFICIENT_SCOPEKey lacks the scope required for this endpoint
{
  "success": false,
  "error": {
    "message": "Invalid or revoked API key.",
    "code": "INVALID_API_KEY",
    "details": {}
  },
  "requestId": "c1b2a3d4-e5f6-7890-abcd-ef1234567890"
}

​
Rate limiting

60 requests per minute per API key. Every response includes:
HeaderDescription
x-ratelimit-limitMaximum requests per minute (always 60)
x-ratelimit-remainingRequests remaining in the current window
x-ratelimit-resetUnix timestamp when the window resets
Retry-AfterSeconds to wait — present only on 429 responses

​
Key rotation

  • Create first, then revoke — update your application before revoking the old key. Revoking first causes downtime.
  • One key per environment — separate keys for development, staging, and production.
  • One key per service — revoke one without affecting others.
  • Rotate regularly — every 90 days at minimum; immediately if a key is exposed.
  • Audit periodically — revoke keys that are no longer in use.