Authentication

Tulu Switch uses short-lived JWT authentication for all API calls. Exchange your API key pair for an access token, then use that token as a Bearer credential on every request.

Call POST /v2/auth/authenticate with your public and secret key to receive an accessToken and refreshToken.
Pass the accessToken in the Authorization: Bearer header on all API requests.
When the access token expires, call POST /v2/auth/refresh to get a new pair without re-authenticating.

POST /v2/auth/authenticate

Exchange your API key pair for a short-lived access token.

Request

curl -X POST "https://api.sandbox.switch.tulupay.com/v2/auth/authenticate" \ \
  -H "Content-Type: application/json" \
  -d '{
  "publicKey": "pk_test_Abc123...",
  "secretKey": "sk_test_Xyz789...",
  "ttl": 900
}'

publicKey — your public key (pk_test_... or pk_live_...)

secretKey — your secret key (sk_test_... or sk_live_...)

ttl — optional, token lifetime in seconds. Default: 900 (15 min), max: 86400 (24 h)

Response

{
  "success": true,
  "statusCode": 200,
  "message": "Success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 900,
    "environment": "TEST"
  }
}

accessToken — use as Authorization: Bearer <accessToken> on all requests

refreshToken — use to get a new access token when it expires (default TTL: 7 days)

expiresIn — access token lifetime in seconds

environment — TEST or LIVE, derived from the key prefix

Using the access token:

Authenticated request

curl -X POST "https://api.switch.tulupay.com/v2/purse/deposit" \ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "cus_xxx",
  "currency": "NGN",
  "amount": 5000
}'

Refreshing Access Tokens

Access tokens expire after the configured TTL (default 15 minutes). Use the refresh token to obtain a new access token without re-authenticating with your key pair.

POST /v2/auth/refresh

curl -X POST "https://api.sandbox.switch.tulupay.com/v2/auth/refresh" \ \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "ttl": 900
}'

Refresh tokens rotate on every use. Each /v2/auth/refresh call invalidates the previous refresh token and issues a new one. Store the latest refresh token after every refresh call.

Environment Resolution

Tulu Switch has two separate base URLs — one per environment. Use the matching base URL and key prefix together.

Environment	Base URL	Key prefix
TEST (sandbox)	`https://api.sandbox.switch.tulupay.com`	`pk_test_` / `sk_test_`
LIVE (production)	`https://api.switch.tulupay.com`	`pk_live_` / `sk_live_`

LIVE Access Requirements

Using LIVE keys (pk_live_) is gated. Your account must satisfy all of the following:

Email address verified
Account status is ACTIVE
KYB compliance status is APPROVED

Requests using LIVE keys on an account that does not meet these requirements will receive a 403 Forbidden response.

Refer to the KYB & KYC Verification guide to complete your compliance review.

Best Practices

Store your secret key in environment variables or a secrets manager — never in source code
Cache the access token and reuse it until it expires; do not re-authenticate on every request
Implement proactive token refresh a minute before expiry to avoid 401 errors mid-request
Store the refreshed refresh token after every /v2/auth/refresh call (tokens rotate)
Rotate your API key pair periodically from the dashboard
Use TEST keys for all development and staging work; never use LIVE keys against non-production systems