Authentication

API v2 uses two credentials on every authorized call:

The API key is not clientCode. Putting the key in the JSON body will not authenticate the request.

See also Auth.CreateToken and Session.Create.

1. Resolve The Tenant With The API Key

Send the key you received from Tristar as a header:

X-Api-Key: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

ApiKey is also accepted. The key is required unless you call a tenant-specific subdomain that already maps to that customer.

Do not send the key as clientCode. clientCode is the short tenant code (for example TRISTAR). It is optional when X-Api-Key is present. If you do send clientCode, it must match the tenant the key belongs to.

2. Get A Contact Token

POST /Auth/Token is anonymous, but tenant resolution still applies. Include X-Api-Key, then the contact email and password from the tenant Contact record.

POST /Auth/Token
Content-Type: application/json
X-Api-Key: {api-key}

{
  "userId": "contact@example.com",
  "password": "your-password"
}

curl -sS -X POST "https://tristarapi-v2.tristar-ops.net/Auth/Token" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d "{\"userId\":\"contact@example.com\",\"password\":\"your-password\"}"

A successful response includes a JWT:

{
  "token": "eyJhbGciOi...",
  "tokenType": "Bearer",
  "expiresInMinutes": 60,
  "customerCode": "ABC001",
  "contactCode": 456,
  "contact": "Maria Contact"
}

POST /Session/Create accepts the same headers and body. It returns the JWT in sessionGuid for compatibility with the legacy session shape. Prefer Auth/Token for new integrations.

Employees use Employee.SignIn with Server check-in credentials instead of a contact email.

3. Call Authorized Endpoints

Send both headers on later requests. The key still selects the tenant; the token identifies the user.

GET /ProcessStatus/Search
X-Api-Key: {api-key}
Authorization: Bearer eyJhbGciOi...

curl -sS "https://tristarapi-v2.tristar-ops.net/ProcessStatus/Search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_TOKEN"

In Swagger, authorize with the API key scheme and the Bearer token. Setting only one of them is not enough for authorized routes.

Common Failures

Use the v2 Swagger at https://tristarapi-v2.tristar-ops.net/swagger. The host tristarapi.tristar-ops.net is the legacy API and does not accept X-Api-Key.