Authentication & Token Issuance

HeldSway uses API Key credentials to issue short-lived Bearer access tokens. All protected endpoints in the HeldSway REST API require this token.

Authentication Flow

sequenceDiagram
    participant Client as Your Server / App
    participant HeldSway as HeldSway API
    Client->>HeldSway: POST /v1/auth/token (api_key + api_secret)
    HeldSway-->>Client: 200 OK (access_token, expires_in, scopes)
    Client->>HeldSway: GET /v1/affiliates (Authorization: Bearer <access_token>)
    HeldSway-->>Client: 200 OK (data)

Obtain API Credentials: Generate your api_key and api_secret from the business dashboard under Settings → API Keys.
Issue Token: Call POST /v1/auth/token with your credentials.
Attach Header: Pass the issued token in the Authorization header on all subsequent requests:
```
Authorization: Bearer <access_token>
```

Available API Scopes

Each API Key is granted a specific set of scopes. The issued token inherits these permissions:

Scope	Grants Access To
`affiliates:read`	List and view affiliates, referral links, affiliate stats, link stats, and commission data
`affiliates:write`	Create, update, delete, approve, suspend, and reactivate affiliates; create links; manage overrides
`orders:read`	List conversions, inspect details, view aggregate order stats, and export orders
`orders:write`	Approve, reject, and bulk-moderate conversion commissions
`reports:read`	View performance statistics, commission charts, top affiliates, clicks by campaign, and analytics query data
`settings:read`	View business settings, portal branding, commission tiers, and payout configuration
`settings:write`	Update business settings, portal branding, commission tiers, and payout configuration
`payouts:read`	List payouts, payout requests, aggregate statistics, CSV exports, and download statements
`payouts:write`	Transition payout status (`processing`, `complete`, `fail`), run bulk payouts, and moderate requests
`connections:read`	Retrieve external business integration connection status
`connections:write`	Disconnect the external business integration

Token Issuance — `POST /v1/auth/token`

Exchange your business’s API Key and Secret for a Bearer access token.

Method: POST
Path: /v1/auth/token
URL: https://api.heldsway.com/api/v1/auth/token
Authentication: None (public endpoint authenticated by payload credentials)
Rate limit: 120 requests/minute
Subscription requirement: None (accessible regardless of plan status)

Request Headers

Content-Type: application/json
Accept: application/json

Request Body

Field	Type	Required	Constraints	Description
`api_key`	string	Yes	max 64 characters	Your business API key (e.g. `key_live_...`)
`api_secret`	string	Yes	max 128 characters	The secret associated with your API key

Example Request

curl -X POST "https://api.heldsway.com/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "api_key": "key_live_01HXYZ1234567890",
    "api_secret": "sec_live_98ABC76543210FEDCBA0987654321"
  }'

Success Response — HTTP 200 OK

{
  "success": true,
  "message": "Token issued successfully.",
  "data": {
    "access_token": "7b8e2f1a9c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f",
    "token_type": "Bearer",
    "expires_in": 14400,
    "scopes": [
      "affiliates:read",
      "affiliates:write",
      "orders:read",
      "orders:write",
      "reports:read",
      "settings:read",
      "settings:write",
      "payouts:read",
      "payouts:write"
    ]
  }
}

Response Fields

Field	Type	Description
`access_token`	string	Opaque Bearer token string to pass in the `Authorization` header
`token_type`	string	Token type (always `"Bearer"`)
`expires_in`	integer	Token lifetime in seconds (14,400 seconds = 4 hours)
`scopes`	string[]	Array of permission scopes granted to this token

Using the Token

Include the access token in the Authorization header for all requests:

curl -X GET "https://api.heldsway.com/api/v1/affiliates" \
  -H "Authorization: Bearer 7b8e2f1a9c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f" \
  -H "Accept: application/json"

Token Lifecycle & Expiry

Validity Period: Tokens expire after 4 hours (expires_in: 14400).
Refresh Strategy: Call POST /v1/auth/token to obtain a fresh token before expiration. A recommended strategy is to request a new token when less than 10 minutes remain.
Storage: Store tokens securely in server memory or a protected cache (such as Redis). Never expose your api_secret or access_token in frontend client code.

Error Reference

HTTP Status	Error Code	Description
`401`	`UNAUTHORIZED`	Invalid API credentials or the key is inactive/expired
`403`	`FORBIDDEN`	The business associated with this API key is inactive
`422`	`VALIDATION_FAILED`	Missing `api_key` or `api_secret` in request payload
`429`	`TOO_MANY_REQUESTS`	Rate limit exceeded (120 req/min limit)
`503`	`SERVICE_UNAVAILABLE`	Authentication backend is temporarily unavailable

Error Response Examples

Invalid Credentials (401)

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API credentials."
  }
}

Inactive Business (403)

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "The business associated with this API key is inactive."
  }
}

Validation Error (422)

{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The given data was invalid.",
    "details": {
      "api_key": ["The api_key field is required."]
    }
  }
}

← Overview Affiliate Management →