Authorize endpoint

The authorization endpoint begins the sign-in flow. It is a browser navigation, not an API call — open it in the user’s browser (native apps: the system browser per RFC 8252, never a WebView). EntryBit runs login and consent, then 302-redirects back to your app with a one-time code.

GET /api/oauth/authorize

Parameters

Passed as query parameters.

Building the request

GET /api/oauth/authorize
      ?response_type=code
      &client_id=eb_9f1c2ab34cd56ef7
      &redirect_uri=entrybitresident://oauth/callback
      &scope=openid%20profile%20email%20offline_access%20passes:read
      &state=<random>
      &code_challenge=<base64url(sha256(verifier))>
      &code_challenge_method=S256
      &nonce=<random>

Most OAuth libraries build this for you — see the React Native quickstart. The state and PKCE values are typically generated and verified by the library.

prompt and max_age

prompt controls the interaction:

• none — never show UI. If login or consent would be required, the request fails fast with login_required or consent_required (redirected as an error). none must stand alone — it cannot be combined with other values.
• login — force a fresh sign-in even if a session exists. (It is stripped from the resumed request internally so it cannot loop.)
• consent — always show the consent screen, even if consent was previously remembered.

max_age requests a maximum authentication age in seconds: if the session’s auth_time is older, the user must re-authenticate. Use prompt=login or a small max_age before a sensitive screen when you need a fresh login — the resulting id_token carries an updated auth_time and amr. See ID token & UserInfo.

Success response

On success EntryBit issues a 302 redirect to your redirect_uri:

HTTP/1.1 302 Found
Location: entrybitresident://oauth/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=<same>&iss=https://entrybit.net

The code is single-use, has a 60-second TTL, and is bound to your client_id, redirect_uri, and PKCE challenge. Exchange it immediately at the token endpoint.

The iss parameter (RFC 9207)

Every authorization response — success and error — carries iss=https://entrybit.net (RFC 9207, authorization-server mix-up mitigation). If your library validates it, it must equal the issuer; otherwise it is safe to ignore.

Error responses

How an error is returned depends on when it is detected:

• Invalid client_id or redirect_uri — a flat, non-redirecting 400. The pair is validated before any redirect happens, so a bad request can never bounce the browser to an attacker-controlled URL. This is the open-redirect and enumeration guard.
• Any protocol error after that point — redirected back to your redirect_uri with error, error_description, state, and iss:

HTTP/1.1 302 Found
Location: entrybitresident://oauth/callback?error=access_denied&error_description=...&state=<same>&iss=https://entrybit.net

Error descriptions are deliberately generic — branch on the error code, never the prose. The codes you may see here include access_denied (user declined), invalid_scope, invalid_request, login_required, consent_required, and interaction_required. Full catalog: Errors.

What happens mid-flow

If the user is not signed in, EntryBit sends the browser to its own login page (/auth?return_to=<this request>) and resumes the authorization once login, 2FA, or passkey completes. Consent is remembered per user, client, and scope: a repeat or narrower request stays silent; a superset re-prompts. None of this changes your app’s code — it targets this endpoint either way.

Next: exchange the code at the Token endpoint.