Authentication

API keys and permission scopes.

API keys

Harpoon uses API keys, issued from your dashboard. Pass them as a Bearer token:

Plain Text

Authorization: Bearer hpn_live_sk_your_api_key_here

The full key is shown once at creation — store it immediately. Lost keys cannot be recovered, only revoked and replaced.

Key types

Type	Format	Use
Secret	`hpn_{env}_sk_*`	Server-side only. Full access.
Public	`hpn_{env}_pk_*`	Browser-safe. Limited scopes.

{env} is live or test.

Public keys cannot:

Set a custom webhook_url on initialize.
Hold scopes other than transactions:read or transactions:initialize.

Scopes

Scope	Purpose	Browser-safe
`transactions:read`	Read transaction status	Yes
`transactions:initialize`	Create payments without custom webhook	Yes
`transactions:write`	List, reconcile, cancel	No
`webhooks:manage`	Create / update / delete / test webhook endpoints	No
`reports:read`	Reports and analytics	No
`team:manage`	Team management	No

Defaults

Key type	Default scopes
Secret	`transactions:read`, `transactions:write`
Public	`transactions:read`, `transactions:initialize`

IP whitelisting

Optionally restrict an API key to specific IPs or CIDR ranges. Configure from API Keys → IP Whitelist. Requests from non-whitelisted IPs return 403.

Rate limits

Default: 100 requests per minute per API key.

429 Too Many Requests includes:

Plain Text

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1704715600
Retry-After: 30

Browser usage

Use a public key. Don’t ship secret keys to a browser.

JavaScript

const HARPOON_PUBLIC_KEY = 'hpn_live_pk_your_key_here';

await fetch('https://api.harpoonsms.com/v1/transactions/initialize', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${HARPOON_PUBLIC_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: '150.00',
    phone_number: '0244123456',
    description: 'Order payment'
  })
});

For status updates from the browser, either poll GET /v1/transactions/{reference} or rely on webhooks configured server-side.

Revoking a key

Settings → API Keys → revoke. Revoked keys are invalidated immediately.

Payments API →

Set up

Webhooks →