Skip to content

Authentication

The Gestix API uses two distinct authentication mechanisms depending on your use case.

Security Schemes

1. API Token Authentication (apiTokenAuth)

Used only with GET /helo to exchange a long-lived API Token for a short-lived session token.

  • Type: HTTP Bearer
  • Header: Authorization: Bearer <api-token>
  • Token format: API Token generated in Admin > Webshop in the Gestix interface
GET /api/{account}/v4.0.0/helo
Authorization: Bearer YOUR_API_TOKEN

2. Session Token Authentication (sessionAuth)

Used for all other protected endpoints after obtaining a session token from /helo or /auth.

  • Type: HTTP Bearer
  • Header: Authorization: Bearer <xa-token>
  • Token format: Short-lived session token (xa-token) returned by /helo or /auth
GET /api/{account}/v4.0.0/invoices
Authorization: Bearer YOUR_SESSION_TOKEN

Authentication Flows

Flow A — API Token (server-to-server)

Recommended for automated integrations, scripts, and backend services.

1. Admin generates an API Token in Gestix → Admin > Webshop
2. Client sends: GET /helo with Authorization: Bearer <api-token>
3. Server returns: { "xa-token": "..." }
4. Client uses xa-token for all subsequent requests

GET /api/03101176/v4.0.0/helo
Authorization: Bearer eyJhbGciOi...

{
  "xa-token": "aaMDAwMDAwMDAwMDAxMzY4ODY5OTA4ICAgRlIwMDA3MTQwNjIxXX"
}

Flow B — Username & Password (user-facing applications)

Recommended for web apps or portals where the end user provides their Gestix credentials.

1. User provides username + password
2. Client sends: POST /auth?username=...&password=...
3. Server returns: { "xa-token": "..." }
4. Client uses xa-token for all subsequent requests

See POST /auth for details.

Generating an API Token

  1. Log into Gestix ERP as an administrator
  2. Navigate to Admin > Webshop
  3. Generate a new API Token
  4. Store it securely — treat it like a password

Keep your API Token secret

The API Token is long-lived. Do not commit it to source control or expose it in client-side code. Rotate it if you suspect it has been compromised.

Session Token Lifetime

The xa-token returned by /helo and /auth is short-lived. Your integration should handle token expiry by catching 403 responses and re-authenticating.

Nonce Requirement

Write operations (POST, PUT) require a nonce query parameter — see the Session Management page for details.