Quickstart
Authenticate against the sandbox and make your first Partner API call.
This takes you from nothing to a verified call against the partner sandbox.
1. Choose an environment
Staging doubles as the partner sandbox — there is no separate one. Build and test there, then move to production.
| Environment | Base URL |
|---|---|
| Sandbox (staging) | https://api-stg.cf.journey.com/v1 |
| Production | https://api-prd.cf.journey.com/v1 |
The version is already in the base URL and in every path you will see in the
reference. Do not append /v1 twice.
2. Authenticate
Today: X-API-Key
Send a Journey API key in the X-API-Key header:
X-API-Key: jny_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx- Only partner-level and admin-level keys are accepted. A service-level
key is rejected with
403. - A revoked or expired key returns
401. X-API-Keyis deliberately not in the CORS allow-list, so this method is server to server only. It will not work from a browser.
Sending a jny_ key as Authorization: Bearer returns
401 Invalid or expired token. The Bearer scheme is for WorkOS access
tokens, not API keys. Older examples showing Bearer jny_… are wrong.
Also supported: WorkOS access tokens
Authorization: Bearer <WorkOS JWT> authenticates an operator's session, which
is how Journey's own surfaces call the API.
Coming soon: WorkOS organization keys
Organization-scoped WorkOS API keys are planned, with Authorization: Bearer
as the primary form and X-API-Key also accepted. They are not accepted
yet — build against X-API-Key today. See
Partner authentication.
3. Make your first call
GET /v1/partner/scope is the right first request: it tells you which
organization your credential belongs to and which venues it can reach, which
is what should drive everything else.
curl "https://api-stg.cf.journey.com/v1/partner/scope" \
-H "X-API-Key: $JOURNEY_PARTNER_API_KEY"Then read some real data:
curl "https://api-stg.cf.journey.com/v1/partner/reservations?limit=25" \
-H "X-API-Key: $JOURNEY_PARTNER_API_KEY"4. Understand what you got back
A few conventions apply everywhere, and they are worth knowing before you write any more code.
X-API-KeyheaderstringrequiredYour partner API key. Server to server only.
Idempotency-KeyheaderstringOptional, and supported on every POST, PUT, PATCH and DELETE under
/partner. Strongly recommended on writes.
- Scopes. Each route requires one or more permissions. The reference shows them as pills on every endpoint. Where a controller and a handler each declare permissions, you need both.
- Organization comes from your credential. Partner callers cannot pass
?organizationId— it is ignored. - 404 means "not found, or not yours". Out-of-scope resources are deliberately indistinguishable from ones that do not exist.
- Responses are additive. New fields appear over time; ignore any you do not recognise rather than failing on them.
5. Pick a pattern
Most integrations are one of five shapes. Each guide has the call sequence and the things that catch people out.
Front-desk fulfillment
Arrivals, verification codes and recording a benefit as delivered.
Roster sync
Reservations into your CRM or warehouse, with cursor pagination.
Program configuration
Programs, tiers, benefits and multipliers as code.
Guest invites
Get an unlinked stay credited to a member.
Code pools
Bulk promo-code inventory.
Errors and retries
The conventions to build against before you scale up.