Authentication

Overview

All Payment Gateway API calls (except tokenization, which uses your public key) require a Bearer token obtained via the /oauth/token endpoint.

Key characteristics:

• Grant type: Client Credentials (machine-to-machine)
• Token lifetime: Short-lived (typically 1 hour) — request a new token when expired
• Transport: Always use HTTPS; never send credentials over unencrypted connections
• Storage: Tokens should be stored securely server-side; never expose them in client-side code

Obtaining an Access Token

POST /oauth/token

Request

curl -X POST https://{FQDN}/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "secretId": "YOUR_CLIENT_SECRET"
  }'

Response (Success — 200)

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

Response (Unauthorized — 401)

{
  "status": 401,
  "message": "Unauthorized request",
  "responseCode": "SE_001"
}

Using the Token

Include the access token in the Authorization header of every API request:

curl -X POST https://{FQDN}/v2/payment \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIs...' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Token Management Best Practices

1. Cache tokens — Reuse the same token until it expires rather than requesting a new one per API call. The authentication endpoint has a rate limit of 60 requests/minute.

2. Handle expiry gracefully — When you receive a 401 or 403 response, request a new token and retry the original request.

3. Never expose credentials client-side — The clientId and secretId must only be used from your backend server (Backend-for-Frontend pattern). The only client-side credential is the publicKey used for card tokenization.

4. Rotate secrets periodically — Contact the Inyo team to rotate your client secret if you suspect it has been compromised.

Authentication vs. Tokenization

Rate Limits

When rate-limited, the API returns HTTP 429. Implement exponential backoff with jitter in your retry logic.