Skip to main content

Authentication

Every /v1 request is authenticated with an API key sent in the X-API-Key header. GET /health is the only call that needs no key.

Send your key​

Add the header to every request. Keys are case-sensitive, opaque strings: do not parse them.

  • Sandbox keys start with tp_test_; live keys start with tp_live_. Both are followed by 43 URL-safe characters (A–Z a–z 0–9 _ -), 51 characters in total.
  • The key is checked before the request body, so an invalid key answers 401 even when the body is also invalid.
  • Do not send provider credentials or an auth object: your provider accounts are configured on our side.
curl -s -X POST "https://transfers-sandbox.pathfndr.io/v1/search" \
  -H "X-API-Key: $TP_API_KEY" \
  -H "Content-Type: application/json" \
  -d @search.json

Authentication errors​

A missing, malformed, unknown, revoked or expired key answers 401 unauthorized in the standard error envelope, with a WWW-Authenticate: ApiKey header="X-API-Key" header. A key used on the wrong environment (a sandbox key on the live URL, or the reverse) also answers 401: see Environments.

Do not retry a 401 unchanged. Check the key and the base URL.

401 Unauthorized
HTTP/1.1 401 Unauthorized
WWW-Authenticate: ApiKey header="X-API-Key"
X-Request-Id: 2f8e1d7b-0d4b-4a57-9a51-3c2f8e1d7b20
Content-Type: application/json

{"error": {"code": "unauthorized", "message": "Invalid API key",
           "provider": null, "request_id": "2f8e1d7b-0d4b-4a57-9a51-3c2f8e1d7b20"}}

Getting and managing keys​

  1. Ask your Pathfndr account manager for access (or write to success@pathfndr.io). We create an account for your company and enable the providers agreed with you.
  2. You receive a sandbox key first. Your live key follows once your integration has passed the go-live checklist.
  3. Each key is shown to you once. Store it in a secrets manager; never put it in source code, browser or mobile apps, or logs.

Rotation. Your account can hold more than one active key. To rotate, ask us for a new key, deploy it, then ask us to revoke the old one. If a key leaks, ask us to revoke it immediately. A revoked key stops working within about a minute.

Providers per key. Your key determines which providers you can use. Search only queries your enabled providers; the other endpoints answer 403 provider_not_enabled for any other provider.

Data isolation. Offer tokens, booking tokens and bookings are bound to your account. Another account's key cannot read or cancel your bookings (404 booking_not_found) or use your tokens (422).

Keep keys server-side

Call the API from your servers only. A key embedded in a web page or mobile app can be extracted and used to make bookings on your account.