ReferenceAPI Reference

Authentication

Issuing, scoping, rotating, and revoking Tripistic API credentials for the beta public API.

July 1, 20264 min read

Status: beta — the public resource surface is live. The public API is in open beta: tours, availability, bookings, customers, departures, guides and vehicles are callable today on api.tripistic.com with a scoped API key. The surface remains subject to beta changes. Keys are issued in Settings → API keys in the dashboard.

The intended design supports three access modes. The bearer-token mode is live for the beta /v1 resource surface; the session and guest-token modes belong to the first-party application.

Mode	Used by	Credential
API token	Server-side integrations, automation, scripts	`Authorization: Bearer <token>`
Session cookie	The first-party web application	HTTP-only session cookie
Public token	Guests viewing a specific booking or itinerary	Unguessable token in the URL

API tokens

Issuing (available — beta)

Create keys in Settings → API keys. Give the key a descriptive name — zapier-prod, accounting-sync, ota-bridge — choose the environment (live/test) and pick only the scopes the integration needs; there is no wildcard scope. The secret is shown once. Store it in your secret manager immediately. Keys are stored hashed (SHA-256) and can be revoked at any time; revocation is permanent.

Keys issued today authenticate the beta resource endpoints on api.tripistic.com. Use bookings:write only for integrations that create bookings; the status banner above always tells the truth.

Using (beta — live)

curl https://api.tripistic.com/v1/tours \
  -H "Authorization: Bearer $TRIPISTIC_API_KEY"

Every request must carry the key in the Authorization: Bearer header. There is no workspace id in the URL — the workspace comes from the key itself, and a key can never read across workspaces.

Scoping

A key carries explicit scopes (there is no wildcard) and is bound to a single workspace. It cannot reach another workspace's data even if the caller knows the ID — cross-workspace reads return 404 for list/get semantics, and a key whose workspace disagrees with its request context is refused with 403.

Issue the narrowest scopes that satisfy the integration:

Integration	Scopes
Website / price widget	`tours:read`, `availability:read`
Reporting export	`bookings:read`, `customers:read`
Booking sync from an OTA	`bookings:read`, `bookings:write`

Rotating

Create the replacement key.
Deploy it to your integration.
Confirm traffic on the new key.
Revoke the old key.

Rotate on a schedule, and immediately whenever someone with access to the secret leaves.

Revoking

Revocation is immediate — in-flight requests using the revoked key fail with 401.

Storage rules

Never commit keys to source control. Use environment variables or a secret manager.
Never embed a key in client-side JavaScript, a mobile app bundle, or a browser extension. Anything shipped to a browser is public.
Never log the Authorization header.
Never send keys over unencrypted channels or paste them into support tickets.

If a key is exposed, revoke it first and investigate second.

Errors

Status	Code	Cause
401	`UNAUTHENTICATED`	Missing, malformed, expired, or revoked token
403	`FORBIDDEN`	Valid token, insufficient role or wrong workspace
429	`RATE_LIMITED`	Too many requests for this credential

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This credential does not have access to workspace ws_01H9"
  }
}

Distinguish the two in your client: 401 means fix the credential, 403 means fix the scope or role. Neither should be retried unchanged.

Public token access

Guest-facing endpoints authenticate with an unguessable token in the URL rather than a credential:

GET /api/public/bookings/{publicToken}
GET /api/public/itineraries/{publicToken}

These are scoped to a single record and grant only what a traveller needs — viewing the booking, paying, signing a waiver, reading the trip timeline. Treat public tokens as sensitive: anyone with the URL has that access. They can be rotated per booking if a link is exposed.

Public catalog endpoints

Tour catalog and availability endpoints under /api/public/{workspaceSlug}/ are unauthenticated by design, so booking widgets can run in the browser. They expose only what you have chosen to publish, and are rate-limited by IP.

Session authentication

The first-party application uses HTTP-only, same-site session cookies with CSRF protection. Sessions rotate on privilege change and are invalidated when a member is removed. Session auth is not intended for third-party integrations — use an API token.

Webhook authentication

Webhooks authenticate in the other direction: Tripistic signs each delivery so you can verify it came from us. Always verify before acting on a payload. See Webhooks.

Checklist

[ ] Key stored in a secret manager, not source control
[ ] Narrowest sufficient role
[ ] Rotation scheduled and documented
[ ] 401 and 403 handled distinctly
[ ] 429 handled with backoff
[ ] Webhook signatures verified

REST API · Rate Limits · Examples