Authentication

The Partner API uses bearer token authentication. You exchange a long-lived API key/secret pair for a short-lived access token, then send that token on every authenticated request.

1. Exchange credentials for a token

POST /api/v1.1/auth/token
Content-Type: application/json

{
  "key": "your-api-key",
  "secret": "your-api-secret"
}

This endpoint itself requires no authentication — your key and secret are the credentials being verified. On success (200):

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJI…",
    "token_type": "Bearer",
    "expires_in": 3600,
    "expires_at": "2026-07-31T12:00:00.000Z"
  },
  "meta": { "timezone": "UTC" }
}

These response fields are snake_case (access_token, not accessToken) — a deliberate exception so existing OAuth2 client libraries work against it. Every other endpoint in this API is camelCase.

2. Send the token on every request

Authorization: Bearer <access_token>
Content-Type: application/json

curl "https://api.spenza.com/api/v1.1/sims" \
  -H "Authorization: Bearer $SPENZA_TOKEN"

Two categories of endpoint don’t need this header at all:

The async status poll (GET /api/v3/transactions/{transactionId}) — the transaction ID itself is the credential.
POST /api/v1.1/port-in/eligibility and POST /api/v3/port-in use security: []/role-based auth respectively rather than the standard bearer check — see the API Reference for each.

Every other endpoint requires the bearer token. Any valid token for your account can call any endpoint — there’s no per-key permission scoping today. POST /api/v1.1/sms is the one exception: it additionally requires the account’s Admin role tier.

Token expiry

Tokens are short-lived (1 hour) — check expires_at on the token response and request a new one before it passes. The API doesn’t document a separate refresh-token grant; re-running the key/secret exchange is how you obtain a new token. Build your client to catch a 401 UNAUTHORIZED and transparently re-authenticate rather than hardcoding a refresh interval, since that’s the behavior guaranteed by the contract.

Credential security

The secret never appears in a response after the initial issuance — treat it like a password, not a lookup value.
Server-side only. Never put your API key/secret (or a long-lived bearer token) in a browser, mobile app, or any client an end user can inspect. Exchange for a token on your backend and proxy authenticated calls through it.
One secret manager, not .env in git. Store credentials in your platform’s secrets manager (or at minimum an untracked .env) — see Security & Best Practices.
Rotate on suspicion. If a key/secret may have leaked, contact Spenza support immediately to have it rotated; there is no self-service rotation endpoint in this API.

Common authentication errors

HTTP	`error.code`	Cause	Fix
400	`VALIDATION_ERROR`	`key` or `secret` omitted from the token request body.	Send both fields.
401	`UNAUTHORIZED`	Key/secret pair is wrong at the token exchange, or a bearer token is missing/malformed/expired on a later request.	Double-check the credentials, or re-authenticate for a fresh token.
403	`FORBIDDEN`	Your account’s plan doesn’t include API access, or the token lacks the role tier an endpoint requires.	Upgrade your plan, or use an account/token with the required role.

See Errors for the complete error-code reference.

Next steps

Quickstart — authenticate and make your first real call end to end.
API Reference → Authentication (sidebar) — the full POST /api/v1.1/auth/token operation spec.

Overview

Build

Reference

Help

API Reference

1. Exchange credentials for a token

2. Send the token on every request

Token expiry

Credential security

Common authentication errors

Next steps

​1. Exchange credentials for a token

​2. Send the token on every request

​Token expiry

​Credential security

​Common authentication errors

​Next steps

1. Exchange credentials for a token

2. Send the token on every request

Token expiry

Credential security

Common authentication errors

Next steps