Authentication

InnBucks uses two credentials on each call: a fixed API key and a short-lived access token.

X-Api-Key: <your API key>                  ← on every request
Authorization: Bearer <accessToken>        ← on every request except login
Content-Type: application/json

4.1 Log in

POST {baseUrl}/auth/third-party

curl -sS -X POST "$INNBUCKS_BASE_URL/auth/third-party" \
  -H "X-Api-Key: $INNBUCKS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"username":"your-username","password":"your-password"}'

Request:

{
  "username": "testClient45HUj",
  "password": "password"
}

Response:

{
  "accessToken": "accessTokenValue",
  "responseCode": "00",
  "responseDescription": "Auth successful"
}

Login succeeded only if responseCode is "00" and accessToken is present. Anything else is a failure; the reason is in responseDescription.

4.2 Keep the token fresh

The token lasts 15 minutes unless InnBucks set a different lifetime for your environment.

1. Cache it. Log in once and reuse the token for every request. Don’t log in per request.
2. Refresh early. Record when you got the token and log in again after 14 minutes, so a request never leaves with a token about to expire.
3. Recover from 401. If a request still returns 401 Unauthorized, log in again and retry that request once with the new token. A second 401 means the credentials or the API key are wrong; stop and alert.
4. Share one token across your app’s workers (use your cache: Redis, the Laravel cache, and so on), so a busy app does not log in hundreds of times.

request ─▶ token cached and < 14 min old? ── no ──▶ log in, cache token
              │ yes                                        │
              ▼                                            ▼
          call API ─▶ 401? ── yes ──▶ log in again, retry once ─▶ 401 again? ─▶ stop, alert
              │ no
              ▼
           response

4.3 Store credentials safely

# .env - never commit this file
INNBUCKS_BASE_URL=https://<test-base-url-from-innbucks>
INNBUCKS_API_KEY=your-api-key
INNBUCKS_USERNAME=your-username
INNBUCKS_PASSWORD=your-password

# test or production: picks the deep-link scheme (section 5.3) and guards money-moving calls
INNBUCKS_ENV=test

# seconds to keep a token before logging in again (15-minute tokens -> 840)
INNBUCKS_TOKEN_TTL=840

When you go live, only the values change: production base URL, API key, username and password, and INNBUCKS_ENV=production.

4.4 Authentication errors

Symptom	Likely cause	Fix
Login returns a non-00 responseCode	Wrong username or password	Re-copy them from InnBucks’ credentials message
401 on login	Missing or wrong X-Api-Key	Send the API key header on the login request too
401 on a call that worked minutes ago	The token expired	Log in again and retry once (4.2)
401 straight after a fresh login	Test credentials used against production (or the reverse), or the token was sent without Bearer	Check the base URL matches the credentials; send Authorization: Bearer <token>
403, or a non-00 code on one operation only	Your account may not be allowed that operation	Ask InnBucks what is enabled for your merchant type (3.5)

---

This page is generated from section 4 of the README in README.md. Spotted something wrong? Open an issue.