Docs · Integrate

Apps and redirect URIs

What a client ID is, the rules for redirect URIs, and how to run the same app in development, staging and production.

Every application that signs users in through Gatekeep is an app (OAuth calls it a client). Each app has:

a client ID, like acme-notes: 1 to 64 characters, starting with a letter, then letters, digits, - or _;
a display name, shown on the sign-in page (“Sign in to Acme Notes”);
one or more redirect URIs, where Gatekeep may send users after sign-in.

During early access, we create and update apps for you. Get in touch to add one or change its URIs.

Redirect URI rules

Exact match. Gatekeep compares the whole URI byte for byte: scheme, host, port, path, and query. https://app.example.com/callback and https://app.example.com/callback/ are different.
HTTPS only, except for local development on http://localhost, http://127.0.0.1 and http://[::1].
Register every one you use. A request with an unregistered URI is refused with an error page. Gatekeep never redirects to it.

Development, staging and production

Two common setups:

One app, several URIs. Register http://localhost:3000/auth/callback alongside your production URI. Simple, and fine for small teams.
One app per environment. acme-notes-dev, acme-notes-staging, acme-notes. Keeps environments apart. Paid plans include separate environments.

Register each product as its own app. Users enroll a passkey once and sign in to all of them with it. See Single sign-on and logout.