Authenticate

Exchange your API username, password and microsite id for a token. Every other endpoint needs it in the auth-token header, and one token must carry a whole booking flow.

POST/authentication/authenticate

One token per booking flowDocs

Use the same token from Quote to Book. A new token mid-flow means starting again from Quote, so never refresh a token inside a flow. Start a flow only when the token has at least 60 minutes left.

Request

This is the only endpoint that takes no auth-token header.

Headers

Accept-EncodingstringrequiredDocs

gzip

Content-Typestringrequired

application/json

Body

usernamestringrequiredSpec

Your API username, from your Nava account manager.

passwordstringrequiredSpec

Its password. Read it from an environment variable or a secret store, never from code.

micrositeIdstringrequiredSpec

Your microsite id, from your credentials. Your test and production credentials each have their own.

Response

200 OK

tokenstring

A JWT. Send it as the auth-token header on every other call. It is a custom header, not Authorization: Bearer.

expirationInSecondsintegerTested

Token lifetime: 7200 (120 minutes).

The response has only these two fields: no auditData. Its trace id is in the Travelc-Trace-Id response header, and it is the trace id of the token: every call you make with this token returns the same value in auditData.traceId. Tested

Keep the token out of your logs

Every later response echoes the token in auditData.authToken. Redact it before you log or store a payload.

Request

# Credentials come from the environment, never from code
TOKEN=$(curl -s --compressed -X POST \
  "$NAVA_BASE_URL/authentication/authenticate" \
  -H "Accept-Encoding: gzip" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "'"$NAVA_USERNAME"'",
    "password": "'"$NAVA_PASSWORD"'",
    "micrositeId": "'"$NAVA_MICROSITE_ID"'"
  }' | jq -r .token)

Response 200

{
  "token": "eyJhbGciOiJIUzUxMiJ9.…",
  "expirationInSeconds": 7200
}

Behaviour

120minToken lifetime (7200 s)Docs

60minMinimum left before you start a booking flow

One token per booking flow

Quote, Quote single, Confirm, Prebook and Book must all use the same token. This is mandatory. Docs
A new token mid-flow means starting again from Quote. An auto-refresh interceptor that swaps the token silently breaks flows.
Before Quote, check the token has at least 60 minutes left. If it doesn't, authenticate first and start the flow on the new token.

Static content and back-office calls

Static content calls don't need the booking-flow token. Any valid token works. Docs
For a long-running catalogue sync or back-office job, cache one token per credential and refresh it before it expires.
We recommend one forced re-authentication on a 401 or 403 for these jobs, then failing and alerting. Never do this inside a booking flow, where a new token means a new flow. Unverified

Errors

Status	Cause	What to do
401	Wrong password or a deleted API user. Both return the same body: `{"error":["User not authorized to access"],"status":"UNAUTHORIZED"}`	Check the credential. If it was working before, ask your Nava account manager whether the API user still exists.	Verified
400	`micrositeId` is missing from the body.	Send all three fields.	Verified
401 on a later call	`User … not allowed to access here`: the token is valid, but your account isn't enabled for that endpoint in this environment.	Don't re-authenticate or retry. Ask your Nava account manager to enable it.	Tested

When a working integration suddenly gets 401 on every call, the API user has usually been deleted or its password rotated. Stop retrying, alert a person, and confirm the user with your Nava account manager. Then update the credential in every service that uses it. Verified

Authentication guide
OTP
Quote, the first call of a booking flow
Environments
Conventions

RequestCopy Anchor Link

ResponseCopy Anchor Link

BehaviourCopy Anchor Link

One token per booking flowCopy Anchor Link

Static content and back-office callsCopy Anchor Link

ErrorsCopy Anchor Link

RelatedCopy Anchor Link

Request

Response

Behaviour

One token per booking flow

Static content and back-office calls

Errors

Related