API Guide: Authenticate With OAuth

Get an access token by registering a client, sending the traveller to approve your app, and exchanging the code you get back. The flow is the OAuth authorisation code flow with PKCE (Proof Key for Code Exchange: a one-time secret that stops anyone else redeeming your code). Only the S256 method is accepted.

Steps

Register a client once. Each redirect_uris entry must be https://, or http://localhost or http://127.0.0.1 for development. Leave out token_endpoint_auth_method and you get a confidential client with a secret; send none for a public client such as a mobile app.

curl -X POST https://api.travelyfe.com/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Travel App",
    "redirect_uris": ["https://YOUR_APP.com/callback"],
    "token_endpoint_auth_method": "none"
  }'

The answer (201) carries client_id, and client_secret for a confidential client. Keep both safe.

Create a PKCE pair. Make a random code_verifier. The code_challenge is its SHA-256 hash, base64url-encoded without padding.

Send the traveller to approve. Open this address in their browser. They sign in to Travelyfe, approve the scopes, and come back to your redirect_uri with a code. The state you send is for your own checks.

https://api.travelyfe.com/oauth/authorise
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://YOUR_APP.com/callback
  &response_type=code
  &scope=itineraries:read%20itineraries:write
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &state=YOUR_STATE

Exchange the code within five minutes. The call is form-encoded. Add client_secret if your client has one.

curl -X POST https://api.travelyfe.com/oauth/token \
  -d grant_type=authorization_code \
  -d code=YOUR_CODE \
  -d code_verifier=YOUR_CODE_VERIFIER \
  -d redirect_uri=https://YOUR_APP.com/callback \
  -d client_id=YOUR_CLIENT_ID

{
  "access_token": "YOUR_TOKEN",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "itineraries:read itineraries:write offline_access"
}

Call the API. A Bearer token goes in the Authorization header.

curl https://api.travelyfe.com/v1/itineraries?limit=5 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Travelyfe-Itinerary-Shape: clean"

Refresh before it expires. Access tokens last one hour. A refresh token lasts 90 days and works once: every refresh returns a new pair.

curl -X POST https://api.travelyfe.com/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=YOUR_REFRESH_TOKEN \
  -d client_id=YOUR_CLIENT_ID

What You Get

An access token that acts for one traveller, limited to the scopes they approved.

Scope	Allows
`itineraries:read`	Reading itineraries, days, flights, hotels, packing and expenses; seeing likes and saves
`itineraries:write`	Creating and changing itineraries; liking, disliking, saving and reporting; images
`documents:read`	Listing documents and getting links to their files
`documents:write`	Adding, renaming and deleting documents

Searching Explore needs a token but no scope. A refresh token is always issued; offline_access is accepted and does nothing extra.

If It Doesn't Work

The OAuth routes answer in the standard OAuth error shape, { "error": "invalid_request", "error_description": "..." }, not the API's. All other routes use the API error shape.

invalid_redirect_uri (400): a redirect address is not https:// or localhost.
invalid_client (401): the client id is unknown or the secret is wrong.
invalid_grant (400): the code is wrong, used, older than five minutes, or its verifier or redirect address does not match.
invalid_scope (400): a scope is not one of the four above.
unauthenticated (401) from the API: the token is missing, expired or revoked. Refresh it.
forbidden (403) from the API: the token lacks the scope the route needs; details.required names it.
503 with a Retry-After header: integrations are paused. Try again after that many seconds.

Limits

Ten client registrations an hour per address.
Access tokens last one hour, refresh tokens 90 days, authorisation codes five minutes.

Revoke a token: form field token. It always answers 200.
Travellers can remove an app themselves in the Travelyfe app, in Account > Settings > Integrations.
Errors And Rate Limits
Read Itineraries

API Guide: Authenticate With OAuth

Steps

What You Get

If It Doesn't Work

Limits

Related

On this page