Authentication

Authentication

PayNexus uses API key authentication. Include your key in the request header to access protected endpoints.

API Key Header

Include your API key in every request using the X-API-Key header:

bash 
X-API-Key: your_api_key_here

Alternatively, use Bearer token format:

bash 
Authorization: Bearer your_api_key_here

API Key Types

Type Prefix Usage
Public Key pk_ Read operations only. Safe for client-side use.
Secret Key sk_ Write operations. Server-side only.
Sandbox Key sb_ Sandbox environment testing.

Public Key Permissions

Public keys can only perform read operations:

  • GET /merchant - Get merchant information
  • GET /merchant/payment-accounts - List payment accounts
  • GET /payments/{reference} - Get payment status
  • GET /payments - List payments
  • POST /mpesa/validate-phone - Validate phone number
  • GET /webhooks - List webhooks
  • GET /invoices - List invoices

Secret Key Permissions

Secret keys are required for all write operations:

  • POST /payments/initiate - Initiate payments
  • POST /mpesa/payment/initiate - Initiate STK push
  • POST /webhooks/register - Register webhooks
  • POST /invoices - Create invoices

Permission Reference

Each API endpoint requires specific permissions. The table below shows the required key type and permission scope for each endpoint.

Endpoint Permission Key Type
GET /merchant merchant.read Public or Secret
GET /merchant/payment-accounts merchant.read Public or Secret
GET /payments/{reference} payments.read Public or Secret
GET /payments payments.read Public or Secret
POST /mpesa/payment/initiate payments.create Secret only
POST /mpesa/payment/status payments.read Secret only
POST /mpesa/validate-phone mpesa.validate Public or Secret
POST /webhooks/register webhooks.manage Secret only
PUT /webhooks/{id} webhooks.manage Secret only
DELETE /webhooks/{id} webhooks.manage Secret only
GET /webhooks webhooks.read Public or Secret
POST /invoices invoices.create Secret only
GET /invoices invoices.read Public or Secret
GET /invoices/{invoice} invoices.read Public or Secret
PUT /invoices/{invoice} invoices.update Secret only
DELETE /invoices/{invoice} invoices.delete Secret only
POST /invoices/{invoice}/send invoices.send Secret only

Security Notes

Never expose secret keys

Secret keys (sk_) must only be used server-side. Never commit them to version control or expose them in client-side code.

Use environment variables

Store API keys in environment variables or a secrets manager. Use .env files that are gitignored.

Rotate keys periodically

Regenerate your secret key from the dashboard if you suspect a leak. Old keys can be revoked instantly.