Authentication

Every protected request carries two credentials: an API Gateway key identifying the partner application, and a per-user Cognito ID token (returned as access_token from the token endpoint). The API key is issued at onboarding. The ID token is minted via OAuth 2.0 PKCE against auth.e2e.movmo.io (pre-prod; prod alias is auth.movmo.io).

For the broader picture — payment card handling, traveler PII, and platform controls — see Security & data handling.

What you need

You will end up holding three distinct credentials. They are issued by different systems, rotate independently, and serve different purposes — do not conflate them.

Credential	What it identifies	Used at	Issued by
API key (x-api-key)	Your partner application to API Gateway. Drives rate limit, route allowlist, usage plan.	x-api-key header on every REST call. Never sent on Model Context Protocol (MCP) calls.	Movmo (provisioned in API Gateway at partner onboarding)
client_id + client_secret	Your OAuth client to the token endpoint. Standard OAuth 2.0 confidential-client credentials.	Sent to POST /v1/oauth/token either in the form body or as Authorization: Basic base64(client_id:client_secret).	Movmo (provisioned at OAuth client registration; pre-registered for confidential partners like Aviare)
access_token + refresh_token	A specific end-user’s session, scoped to your client.	Authorization: Bearer <access_token> on REST and MCP. Refresh via the token endpoint.	Movmo’s authorization server, returned from the PKCE exchange

API key and client_secret are not the same thing. The API key controls whether your application can talk to the gateway at all. client_secret controls whether your OAuth client can mint a user token. A leaked API key lets an attacker hit the gateway as your app; a leaked client_secret lets an attacker swap codes for tokens as your client. Store them separately.

Public vs confidential clients:

• Confidential clients (server-to-server OAuth, what Aviare and other commercial partners use) hold client_secret securely in a backend secret store. The token endpoint validates it via client_secret_basic.
• Public clients (DCR-registered MCP agents, browser/native PKCE clients) cannot hold a secret. They register with token_endpoint_auth_method: "none" and omit client_secret from the token exchange — PKCE’s code_verifier is the proof-of-possession instead.

Dynamic Client Registration (RFC 7591) is reserved for autonomous MCP agents and is the public-client path.

How OAuth clients get provisioned

Two distinct paths, depending on what kind of integration you are:

Named commercial partners (airlines, OTAs, TMCs, hotel cross-sells — anyone with backend infrastructure and a long-lived integration) are pre-registered by Movmo. You will receive a stable client_id and a client_secret over a secure channel at onboarding. There is no TTL — your credentials do not silently expire. Rotation is coordinated explicitly between you and Movmo.

Autonomous MCP agents (Claude Desktop, Cursor, ChatGPT connectors, custom MCP clients) self-register at POST /v1/oauth/register per RFC 7591 Dynamic Client Registration. Each install gets a fresh server-assigned UUID client_id. Public clients (token_endpoint_auth_method: "none") authenticate via PKCE alone; confidential clients receive a client_secret. Registrations carry a sliding 30-day TTL that extends on every successful token exchange — abandoned installs eventually expire and any refresh tokens they hold are invalidated.

If you are building a backend integration for a commercial partnership, contact Movmo for pre-registration. Do not register via DCR — your integration deserves a stable identifier and no TTL.

Confidential client redirect URI requirements (verified at registration time):

• Must use https:// — http:// is rejected with invalid_redirect_uri.
• Must not be localhost (or 127.0.0.1, etc.) — local development URIs are rejected. Use a real partner-controlled domain or a tunnel service that exposes HTTPS.

Public clients (PKCE, token_endpoint_auth_method: "none") are allowed http://localhost:* redirect URIs for local development.

OAuth 2.0 PKCE flow

The flow has three actors: your frontend, your backend (where client_secret lives), and Movmo’s authorization server (auth.e2e.movmo.io).

React frontends — use @movmo/connect-button

For React partners, install the @movmo/connect-button package. It bundles the parts of the flow that every partner integration repeats: code_verifier generation, code_challenge derivation via crypto.subtle, state issuance, sessionStorage round-trip, and the redirect to auth.movmo.io.

npm install @movmo/connect-button

Drop the button onto your sign-in page:

import { ConnectMovmoButton } from "@movmo/connect-button";

<ConnectMovmoButton
  clientId="your-client-id"
  redirectUri="https://partner.example.com/oauth/callback"
  isProd // add when you go live — without it the button targets Movmo's e2e environment
/>;

Since v0.3.0 the package defaults to Movmo’s e2e (testing) environment: every Movmo URL, including the auth.movmo.io redirect, derives from the single isProd prop, and omitting it means isProd={false}. Integrate and test without it, then add isProd for production.

On your redirect_uri page, validate state and forward code + code_verifier to your backend:

import { completeMovmoOAuth, StateMismatchError } from "@movmo/connect-button";

const params = new URLSearchParams(window.location.search);
try {
  const { code, codeVerifier } = await completeMovmoOAuth(
    params.get("code"),
    params.get("state"),
  );
  // POST { code, codeVerifier } to your backend, which calls /v1/oauth/token
  // with client_secret server-side.
} catch (err) {
  if (err instanceof StateMismatchError) {
    // CSRF — refuse and start a fresh flow.
  }
  throw err;
}

For partners with their own CTA component or non-button surfaces (custom modals, mobile webviews), the package also exports a headless useMovmoOAuth() hook that returns { startOAuth, isStarting } with the same PKCE machinery.

The package never holds client_secret — that credential cannot reach a browser. The token exchange always runs server-side; see Token exchange below.

Building your own

Partners not on React (Vue, Svelte, plain JS, native mobile) implement the same seven steps directly. Use a standards-compliant OAuth client library — do not hand-roll the flow.

1. [Frontend] User triggers the connect flow from your CTA. Generate a code_verifier (43–128 random chars via crypto.getRandomValues) and derive code_challenge = base64url(sha256(code_verifier)). Hold code_verifier and a CSRF state in sessionStorage for the redirect round-trip; delete after the token exchange completes.
2. [Frontend → Movmo] Redirect to the authorization_endpoint from the discovery document (currently https://auth.e2e.movmo.io/) with response_type=code, client_id, redirect_uri, code_challenge, code_challenge_method=S256, state, and optionally a space-delimited scope (see Scopes and user consent) as query parameters. The auth-ui parses OAuth params from the root URL — there is no /authorize sub-path.
3. [Movmo] The user authenticates on Movmo-hosted pages with an email OTP (SMS delivery applies only when the user has a verified phone and opted in). Your application never sees the credentials. OTP length differs by user state: a brand-new user (Cognito SignUp flow) receives a 6-digit code; a returning user (Cognito custom-challenge flow) receives an 8-digit code. Build any custom OTP UI to handle both. If you requested Movmo scopes the user has not previously granted your client, a consent screen follows sign-in; a denial redirects back with error=access_denied.
4. [Movmo → Frontend] Movmo redirects to your redirect_uri with code and the original state. Validate state matches what you issued.
5. [Frontend → Backend] The frontend forwards code and code_verifier to your backend.
6. [Backend → Movmo] Your backend POSTs to https://e2e.api.movmo.io/v1/oauth/token with grant_type=authorization_code, client_id, client_secret (confidential clients only), code, code_verifier, and redirect_uri. Must run server-side — client_secret cannot reach a browser. Public clients (DCR-registered with token_endpoint_auth_method=none) omit client_secret.
7. [Backend] Movmo returns access_token (a Cognito ID token; send as Authorization: Bearer <access_token>), refresh_token, token_type=Bearer, expires_in=900, and — when the grant carries Movmo scopes — the effective scope string. Persist refresh_token server-side only.

Endpoint locations come from the discovery document at /.well-known/oauth-authorization-server.

Token exchange

Whether you use @movmo/connect-button or hand-roll the flow, the token exchange itself is identical and always runs on your backend with client_secret. See the POST /v1/oauth/token reference for the request shape.

OAuth 2.0 only — no OIDC

The discovery document advertises openid in scopes_supported for forward compatibility, but the token endpoint does not return a separate id_token field today. The access_token is a Cognito ID token (it carries identity claims like sub, email, phone_number) and is the only token you need for both REST and Model Context Protocol (MCP) calls. Treat it as opaque on the wire and rely on the userinfo claims after server-side validation.

Making authenticated requests

REST and MCP have different header requirements:

• REST (/v1/* excluding /v1/mcp): both x-api-key AND Authorization: Bearer <access_token> are required on every protected route.
• MCP (/v1/mcp): Authorization: Bearer <access_token> only. Do NOT send x-api-key — partner usage plans throttle keyed traffic on MCP routes to 0 RPS as a safety net for misuse, returning a 429. JWT verification happens at the MCP server, not the gateway.

REST example, JavaScript:

const res = await fetch("https://e2e.api.movmo.io/v1/users/me", {
  headers: {
    "x-api-key": process.env.MOVMO_API_KEY,
    Authorization: `Bearer ${accessToken}`,
  },
});
if (!res.ok) throw new Error(`Movmo ${res.status}: ${await res.text()}`);
const profile = await res.json();

Go:

client := &http.Client{Timeout: 30 * time.Second}
req, err := http.NewRequestWithContext(ctx, "GET",
    "https://e2e.api.movmo.io/v1/users/me", nil)
if err != nil {
    return fmt.Errorf("build request: %w", err)
}
req.Header.Set("x-api-key", os.Getenv("MOVMO_API_KEY"))
req.Header.Set("Authorization", "Bearer "+accessToken)

resp, err := client.Do(req)
if err != nil {
    return fmt.Errorf("call movmo: %w", err)
}
defer resp.Body.Close()
if resp.StatusCode >= 400 {
    body, _ := io.ReadAll(resp.Body)
    return fmt.Errorf("movmo %d: %s", resp.StatusCode, body)
}

API-key-only routes

Three flights-catalog routes accept the API key alone, with no user JWT. They are booking-flow entry points used before a user session exists:

Method	Path
GET	/v1/flights/providers/{provider}/capabilities
GET	/v1/flights/providers/{provider}/offers/{offer_id}
POST	/v1/flights/providers/{provider}/offers

Every other route requires both headers — with two exceptions that authenticate by other means: POST /v1/oauth/token (your OAuth client credentials and/or PKCE) and POST /v1/identity/resolve (your client_secret_basic credentials; see the identity integration guide). Neither requires x-api-key; sending one anyway is harmless.

Token refresh

access_token lifetime is expires_in seconds (900 on initial exchange). Refresh server-side; on a non-2xx, keep the existing refresh_token:

const res = await fetch("https://e2e.api.movmo.io/v1/oauth/token", {
  method: "POST",
  headers: {
    "x-api-key": process.env.MOVMO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    grant_type: "refresh_token",
    client_id: "aviare-prod",
    client_secret: process.env.MOVMO_CLIENT_SECRET,
    refresh_token: storedRefreshToken,
  }),
});
if (!res.ok) throw new Error(`Refresh failed: ${res.status}`);
const tokens = await res.json();

Refresh tokens are not rotated. The refresh response returns only a new access_token — no new refresh_token — and the original refresh_token continues to work until its TTL expires (Cognito default: 30 days). Persist the refresh_token once at the initial code exchange and reuse it for the lifetime of the user session.

Both client_secret_basic and client_secret_post are supported

The token endpoint accepts confidential-client credentials via either method on both grants. Per RFC 6749 §2.3.1, client_secret_basic (HTTP Basic header) is the spec-preferred method and is what standards-compliant OAuth libraries (golang.org/x/oauth2, openid-client for Node, requests-oauthlib for Python) emit by default — letting the library handle Basic encoding is the recommended approach. client_secret_post (form body) remains supported for clients that cannot easily set headers.

Scopes and user consent

Partner-level OAuth scopes are live. A token minted with scopes is narrowed server-side to exactly those scopes on every request; the user grants them on a Movmo-hosted consent screen during the authorization step.

Requesting scopes

Add a space-delimited scope parameter to the authorization redirect (step 2 of the PKCE flow):

https://auth.e2e.movmo.io/?response_type=code
  &client_id=...&redirect_uri=...&code_challenge=...&code_challenge_method=S256
  &state=...&scope=profile.read%20passengers.read%20bookings.write

The catalog is ten scopes across five domains, all machine-discoverable via scopes_supported on the discovery document (and mirrored on the RFC 9728 protected-resource metadata used by MCP clients). write does not imply read — request both when you need both:

Scope	Grants
profile.read	Read the user’s profile
profile.write	Update profile fields, manage the profile photo
preferences.read	Read travel, locale, and security preferences
preferences.write	Update travel, locale, and security preferences
passengers.read	List and read saved travelers, including travel documents
passengers.write	Create, update, and delete saved travelers
payments.read	List and read saved payment methods (brand + last 4 only)
payments.write	Update and remove saved payment methods
bookings.read	List and read the user’s bookings and trip history
bookings.write	Search flights, build offers, select seats, and create bookings

Unknown scope values are rejected with 400 invalid_scope. The OIDC identity scopes (openid, email, profile) may be sent alongside Movmo scopes and never trigger the consent screen.

The consent screen

When the requested scopes exceed what the user has previously granted your client, the Movmo authorization UI shows a consent screen after sign-in — first-time users see the full list; returning users see only the newly requested permissions, with prior grants listed as already allowed. Each permission is its own checkbox: the user can untick individual scopes before approving rather than accepting or rejecting the whole request (see Granular consent below). Consent is per-client and incremental: approving new scopes merges with prior grants, never replaces them. If the user denies the screen outright, Movmo redirects to your redirect_uri with error=access_denied&error_description=User+denied+consent and your state — handle it as a normal OAuth denial. Requests whose scopes are already fully covered skip the screen entirely.

Granular consent

Consent is granted (and withheld) per scope, not all-or-nothing. A user can approve some of the permissions your scope parameter requested and untick the rest — the resulting authorization code, and the token it exchanges for, are bound to the intersection of what you requested and what the user actually left checked (requested ∩ granted). Never assume a token carries every scope you asked for; read the token response’s scope field to find out what you actually got:

{
  "access_token": "eyJraWQi...",
  "refresh_token": "eyJjdHkiOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "profile.read passengers.read"
}

(Here the client requested profile.read passengers.read bookings.write; the user left bookings.write unchecked, so it’s simply absent from the effective grant.) A call that needs a scope missing from that list fails 403 insufficient_scope (see Enforcement) — handle it by sending the user back through authorization for the missing scope, or by degrading the dependent feature gracefully; don’t assume the scope was granted just because you requested it.

Two more behaviors follow from per-scope consent:

• No consent-screen loop. A scope the user has previously declined for your client is not re-offered on a later authorization — Movmo issues the code without it, silently, rather than prompting again. Only scopes the user has never decided on (not yet granted, not yet declined) trigger the consent screen. A declined scope stays declined until the user restores it themselves from Connected apps (see Revocation).
• All-declined fails the request. If the user unchecks every scope you requested, there is nothing left to authorize and the code request fails with 400 invalid_scope rather than issuing a scope-less code.

The token response scope field

When a grant carries scopes, the token response (both grants) echoes the effective scope set per RFC 6749 §5.1:

{
  "access_token": "eyJraWQi...",
  "refresh_token": "eyJjdHkiOi...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "profile.read passengers.read bookings.write"
}

Always read this field rather than assuming your requested scopes were granted in full — the effective set is the intersection of your request and the user’s current consent. Refresh preserves the original grant’s scopes and never escalates them; if the user has revoked consent since issuance, the refresh grant fails with 400 invalid_scope and error_description telling you to restart the authorization flow.

Enforcement

Every API request made with a scoped token is checked against the granted scopes. A request outside them returns 403 with an RFC 6750 error body:

{
  "error": "insufficient_scope",
  "error_description": "the token's granted scopes do not allow this request",
  "scope": "payments.read"
}

scope names the scope the operation requires — request it (the consent screen will show only the delta) and retry with the new token. The RFC 6750 WWW-Authenticate challenge is also set; note that API Gateway delivers it as x-amzn-remapped-www-authenticate. Administrative and internal operations sit outside the scope catalog entirely and are not reachable with a scoped token, regardless of the user’s own permissions.

Revocation

Users can revoke your application’s access at any time from the Connected apps page in their Movmo account settings. Revocation takes effect within minutes: the user’s active session tokens are invalidated immediately (a refresh attempt returns 400 invalid_grant), and even after that window your refresh grant fails with 400 invalid_scope because the underlying consent is gone. Any still-valid access token stops working when it reaches its own 15-minute expiry. Treat both 400 responses on the refresh grant as “re-authorize from scratch” — send the user back through the authorization flow, where they will see the consent screen again. There is no separate revocation webhook; the token-endpoint error is the signal.

Per-permission management is separate from full revocation. From the same Connected apps page, users can also toggle individual permissions off or back on for a client without disconnecting it — declining one previously-granted scope, or restoring one they’d declined, while the rest of the grant stays intact. This doesn’t invalidate the current access token outright; it takes effect on the client’s next token refresh, where the narrowed (or restored) scope set shows up in the response scope field. Don’t cache a grant’s scope set beyond a single refresh cycle — always trust what the latest token response says over what you last saw.

Tokens without scopes

What happens when the scope parameter is omitted depends on how your client was registered:

• Dynamically-registered clients (RFC 7591, including MCP agents): omitting scope — or sending only the OIDC identity scopes — is treated as requesting the full ten-scope catalog. The user sees the consent screen for all ten permissions, and the issued token is narrowed and enforced exactly as if you had requested them explicitly (the token response echoes the effective scope). To request less, send an explicit scope — least-privilege tokens are safer for your users and show a shorter consent screen.
• Pre-registered partner clients (provisioned with Movmo during onboarding): omitting scope keeps the legacy behavior — the token carries no scope set, no consent screen is shown, and requests are authorized by the user’s own permissions alone. New integrations should still request explicit scopes; the un-narrowed path exists for backward compatibility.

Grants issued before scopes existed continue to refresh without narrowing; the new behavior applies from each client’s next full authorization.