# EntryBit Developer Documentation

> The complete EntryBit API & OAuth documentation as a single document, for LLM ingestion. Canonical HTML lives under https://entrybit.net/docs/. Each page is also available as raw Markdown by appending `.md` to its URL. OpenAPI 3.1: https://entrybit.net/openapi.json


# Get started

## Introduction

Source: https://entrybit.net/docs/get-started/introduction/

The EntryBit API lets your app sign users in with EntryBit, issue and manage guest passes, and integrate your backend — over OAuth 2.0 / OpenID Connect and a Bearer-token REST API.

The **EntryBit API** lets you build on the same platform that powers EntryBit's own apps: sign users in with EntryBit, read and create guest passes, and connect your backend or SDK.

Everything is standard HTTPS + JSON, and everything self-describes at the OpenID Connect discovery document — so most OAuth libraries configure themselves from a single URL.

- **Base URL:** `https://entrybit.net`
- **Discovery:** `GET /.well-known/openid-configuration`
- **Format:** JSON over HTTPS (TLS required); `Cache-Control: no-store` on every credential-bearing response.

## Three ways to authenticate

Pick the model that matches who is acting:

1. **Sign in with EntryBit (OAuth 2.0 / OpenID Connect)** — for apps acting on behalf of a **signed-in user** (e.g. a resident mobile app). Authorization-code flow with **PKCE required**; you receive a short-lived access token (RS256 JWT, ~15 min) and a rotating refresh token. Call `/api/v1/*` with the access token.
2. **Organization API keys** — for **servers and SDKs** acting as the organization. Keys look like `eb_sk_…`, are created by an org admin in **Settings → API keys**, and are shown once. Send as `Authorization: Bearer eb_sk_…`. Call `/api/v1/org/*`.
3. **Discovery & JWKS** — public metadata (`/.well-known/openid-configuration`) and the signing keys (`/.well-known/jwks.json`) that let any resource server verify a token offline.

See [Authentication](/docs/get-started/authentication/) for a side-by-side of when to use which.

## Where to start

- **Building a mobile or web app that signs users in?** Start with the [Quickstart: Sign in with EntryBit](/docs/get-started/quickstart-react-native/), then the [OAuth 2.0 & OpenID Connect](/docs/oauth/overview/) reference.
- **Building a server integration or SDK?** Read [API keys](/docs/api-keys/overview/) and the [Organization API](/docs/api-reference/organization/).
- **Just want the endpoints?** Jump to the [API reference conventions](/docs/api-reference/conventions/).

## Conventions

- **Errors** — protocol endpoints return RFC 6749 / 6750 error objects (`{ "error": … }` with a `WWW-Authenticate` challenge on `401`/`403`). Business endpoints return `{ "success": false, "error": … }`; quota exhaustion is `402`. Branch on the error **code**, never the prose — descriptions are deliberately generic.
- **Rate limits** — per-IP and per-credential buckets; exceeding one returns `429`. Back off and retry.
- **Security** — never place credentials in a URL; all endpoints require TLS. Refresh tokens **rotate** on every use — always persist the newest one.

## Machine-readable specs

The entire surface is published as **OpenAPI 3.1** and as LLM-friendly text:

- **OpenAPI:** [`/docs/api-reference/openapi/`](/docs/api-reference/openapi/) (download / view — point Swagger UI, Redoc, or an SDK generator at it).
- **For LLMs:** [`/llms.txt`](/llms.txt) and [`/llms-full.txt`](/llms-full.txt). Every doc page is also available as raw Markdown — append `.md` to its URL.


## Authentication

Source: https://entrybit.net/docs/get-started/authentication/

OAuth 2.0 signs in users; API keys authenticate servers. Which credential to use, what each looks like, and the one rule that keeps your secret key safe.

EntryBit has two ways to prove who is calling — and they are not interchangeable. Pick by asking **who is acting**: a *person* using your app, or a *server* acting as the whole organization.

- **A signed-in user** → **OAuth 2.0 / OpenID Connect**. Your app never sees the password; it receives a short-lived access token on the user's behalf and calls [`/api/v1/*`](/docs/api-reference/passes/).
- **A backend or SDK** → an **organization API key**. A long-lived secret that acts as the organization and calls [`/api/v1/org/*`](/docs/api-reference/organization/).

## The two credentials at a glance

| | OAuth client | API key |
|---|---|---|
| Acts as | A **signed-in user** | The **organization** |
| Looks like | `eb_9f1c2ab34cd56ef7` (`client_id`) | `eb_sk_…` (secret) |
| Secret? | **No** — the `client_id` is public | **Yes** — a 256-bit secret |
| Proof of identity | The user's login + **PKCE** | The key itself |
| Where it lives | Shipped in the app / SPA | On your server, in a vault |
| Created in | **Settings → Team → OAuth apps** | **Settings → API keys** |
| Token you send | `Authorization: Bearer <access_token>` (a JWT) | `Authorization: Bearer eb_sk_…` |
| Calls | `/api/oauth/*`, `/api/v1/*` | `/api/v1/org/*` |
| Scopes | User-consent scopes (`passes:read`, …) | `org:*` scopes |

## The credential shapes

Both identifiers start with `eb_`, and the difference is the one thing worth memorising:

- **`eb_9f1c2ab34cd56ef7`** — an OAuth **`client_id`**. It has no `sk`. It is **public**: it ships inside your mobile app or SPA, and that is fine because a `client_id` alone can do nothing. The security comes from the user logging in plus **PKCE** (a per-request secret the app proves it holds).
- **`eb_sk_…`** — an organization **API key**. The `sk` means *secret key*. It is 256 bits of CSPRNG output, it acts as the whole organization, and it is shown to you exactly **once**.

### The golden rule

> **Never ship an `eb_sk_…` key inside an app, APK, SPA bundle, or any client anyone can download.** A secret key can be extracted from a shipped binary in minutes, and it grants organization-wide access. Client apps use an OAuth **`client_id`** (public, PKCE-protected); secret keys live only on servers you control. If a secret key was ever committed, embedded, or shared, **[revoke it](/docs/api-keys/create-and-manage/)** and switch the app to a `client_id`.

## Decision table

| You are building… | Use | Start here |
|---|---|---|
| A mobile app that signs users in | OAuth 2.0 (public client + PKCE) | [Quickstart: Sign in with EntryBit](/docs/get-started/quickstart-react-native/) |
| A single-page web app (SPA) | OAuth 2.0 (public client + PKCE) | [OAuth 2.0 & OpenID Connect](/docs/oauth/overview/) |
| A web app with a backend that can keep a secret | OAuth 2.0 (confidential client) | [Register an app](/docs/oauth/register-an-app/) |
| A server integration that acts for the whole org | API key | [API keys](/docs/api-keys/overview/) |
| A cron job / data sync / internal tool | API key | [API keys](/docs/api-keys/overview/) |
| A resource server that only verifies tokens | Discovery + JWKS | [Discovery & JWKS](/docs/oauth/discovery-jwks/) |

## What each model gets you

**OAuth 2.0 / OpenID Connect** — the authorization-code flow with **PKCE (S256), required for every client**. The user signs in through the system browser (never a WebView), your app exchanges the resulting code for tokens, and you receive:

- an **access token** — an RS256 JWT, ~15 minutes, sent as `Authorization: Bearer …`;
- a **refresh token** — opaque, 60-day, **rotating** (when you request `offline_access`);
- an **id_token** — who signed in and *how* (when you request `openid`).

See [OAuth 2.0 & OpenID Connect](/docs/oauth/overview/) for the full flow, and [Scopes](/docs/oauth/scopes/) for what you can ask for.

**Organization API keys** — a single secret that authenticates every request. An org admin mints it in **Settings → API keys** with least-privilege `org:*` scopes, an optional expiry, and an optional source-IP allowlist. Send it on every call and you act as the organization. See [API keys](/docs/api-keys/overview/).

## Next steps

- New to the platform? Read the [Introduction](/docs/get-started/introduction/).
- Signing users in? [Quickstart: Sign in with EntryBit](/docs/get-started/quickstart-react-native/).
- Building server-side? [API keys](/docs/api-keys/overview/) then the [Organization API](/docs/api-reference/organization/).


## Quickstart: Sign in with EntryBit

Source: https://entrybit.net/docs/get-started/quickstart-react-native/

Add Sign in with EntryBit to a React Native (Expo) app in minutes — register a public client, run the PKCE flow with expo-auth-session, exchange the code, and call the API.

This is the short path to **"Sign in with EntryBit"** in a React Native app and calling the API on the user's behalf. It uses `expo-auth-session`, the authorization-code flow, and **PKCE (S256)** — the standard, secure pattern for native apps ([RFC 8252](https://www.rfc-editor.org/rfc/rfc8252)).

- **Base URL:** `https://entrybit.net` (or your staging origin)
- **Auth model:** authorization-code + PKCE via the **system browser** — never a WebView, never an in-app password screen.
- **Everything self-describes:** `GET /.well-known/openid-configuration`

For the full walkthrough with raw HTTP and the *why* behind each choice, the endpoint reference is the [OpenAPI spec](/docs/api-reference/openapi/).

## Step 0 — Register a public client (one-time)

Register a **public OAuth client** in **Settings → Team → OAuth apps** — self-service, any org admin can do it. See [Register an app](/docs/oauth/register-an-app/) for the full field reference.

- **Application type:** Public (mobile / SPA — no secret; PKCE is the proof)
- **Redirect URI:** `entrybitresident://oauth/callback`
- **Scopes:** `openid profile email offline_access passes:read passes:write invites:read`

You get a **`client_id`** like `eb_9f1c…` immediately. That, plus the base URL, is everything the app needs.

> **`client_id` is not an API key.** The `client_id` (`eb_…`, no `sk`) is public and belongs in the app. An **API key** (`eb_sk_…`, from Settings → API keys) is a **server secret** — never put it in an app; anyone can extract it from an APK or bundle. See [Authentication](/docs/get-started/authentication/).

## Step 1 — Install

```bash
npx expo install expo-auth-session expo-crypto expo-secure-store expo-web-browser
```

Declare the custom scheme (the `entrybitresident://` part of your redirect URI) in `app.json`:

```json
{
  "expo": {
    "scheme": "entrybitresident"
  }
}
```

> OAuth with a custom scheme does **not** work in Expo Go — use a development build (`npx expo run:ios` / `run:android`, or an EAS dev client). Do not route OAuth through the old AuthSession proxy.

## Step 2 — Sign in

Three small modules keep this testable: shared config, a secure token store, and the sign-in screen. All of the code below is complete — paste it in and change the `CLIENT_ID`.

`lib/entrybit.ts` — one place for config and the discovery document:

```ts
import * as AuthSession from 'expo-auth-session';

export const ISSUER = 'https://entrybit.net';
export const CLIENT_ID = 'eb_9f1c2ab34cd56ef7'; // from step 0 — public, not a secret

export const redirectUri = AuthSession.makeRedirectUri({
  scheme: 'entrybitresident',
  path: 'oauth/callback',
});

export const SCOPES = [
  'openid', 'profile', 'email', 'offline_access',
  'passes:read', 'passes:write', 'invites:read',
];

// The same document useAutoDiscovery() reads, cached for non-hook code.
let discovery: AuthSession.DiscoveryDocument | undefined;

export async function getDiscovery(): Promise<AuthSession.DiscoveryDocument> {
  return (discovery ??= await AuthSession.fetchDiscoveryAsync(ISSUER));
}
```

`lib/tokenStore.ts` — the access token lives ~15 minutes, so it stays **in memory**; only the durable credentials touch the device keychain:

```ts
import * as SecureStore from 'expo-secure-store';
import type { TokenResponse } from 'expo-auth-session';

const REFRESH_TOKEN_KEY = 'entrybit.refreshToken'; // the durable credential
const ID_TOKEN_KEY = 'entrybit.idToken';           // kept only for logout (id_token_hint)

let accessToken: string | null = null;
let accessTokenExpiresAt = 0; // epoch ms

export async function saveTokens(t: TokenResponse): Promise<void> {
  accessToken = t.accessToken;
  accessTokenExpiresAt = (t.issuedAt + (t.expiresIn ?? 900)) * 1000;

  // Rotation rule: every refresh returns a NEW refresh token — always overwrite.
  if (t.refreshToken) await SecureStore.setItemAsync(REFRESH_TOKEN_KEY, t.refreshToken);
  if (t.idToken) await SecureStore.setItemAsync(ID_TOKEN_KEY, t.idToken);
}

export function getFreshAccessToken(): string | null {
  return Date.now() < accessTokenExpiresAt - 30_000 ? accessToken : null; // 30 s clock skew
}

export const getRefreshToken = () => SecureStore.getItemAsync(REFRESH_TOKEN_KEY);
export const getIdToken = () => SecureStore.getItemAsync(ID_TOKEN_KEY);

export async function clearTokens(): Promise<void> {
  accessToken = null;
  accessTokenExpiresAt = 0;
  await Promise.all([
    SecureStore.deleteItemAsync(REFRESH_TOKEN_KEY),
    SecureStore.deleteItemAsync(ID_TOKEN_KEY),
  ]);
}
```

> **Tokens belong in `expo-secure-store`** (Keychain / Android Keystore) or in memory — never AsyncStorage, never logs, never Redux state persisted to disk.

`app/sign-in.tsx` — the screen. The hook opens the system browser; the effect exchanges the returned code for tokens:

```tsx
import { useEffect, useRef, useState } from 'react';
import { Button, Text, View } from 'react-native';
import * as AuthSession from 'expo-auth-session';
import { CLIENT_ID, ISSUER, redirectUri, SCOPES } from '../lib/entrybit';
import { saveTokens } from '../lib/tokenStore';

export default function SignInScreen({ onSignedIn }: { onSignedIn: () => void }) {
  // Configures every endpoint from /.well-known/openid-configuration.
  const discovery = AuthSession.useAutoDiscovery(ISSUER);
  const [error, setError] = useState<string | null>(null);
  const exchangedCode = useRef<string | null>(null);

  const [request, response, promptAsync] = AuthSession.useAuthRequest(
    {
      clientId: CLIENT_ID,
      redirectUri,
      responseType: 'code',
      usePKCE: true, // S256 — the server rejects requests without it
      scopes: SCOPES,
    },
    discovery,
  );

  useEffect(() => {
    // 'cancel' / 'dismiss' mean the user backed out — nothing to do.
    if (!discovery || !request?.codeVerifier || response?.type !== 'success') return;

    // An authorization code is single-use — exchanging it twice revokes the
    // grant — so guard against effect re-runs before exchanging.
    const { code } = response.params;
    if (exchangedCode.current === code) return;
    exchangedCode.current = code;

    AuthSession.exchangeCodeAsync(
      {
        clientId: CLIENT_ID,
        code,
        redirectUri,
        extraParams: { code_verifier: request.codeVerifier },
      },
      discovery,
    )
      .then(saveTokens) // { accessToken, refreshToken, idToken, expiresIn: 900 }
      .then(onSignedIn)
      .catch(() => setError('Sign-in failed. Please try again.'));
  }, [discovery, request, response, onSignedIn]);

  return (
    <View>
      <Button
        title="Sign in with EntryBit"
        disabled={!request} // null until discovery and the PKCE pair are ready
        onPress={() => promptAsync()}
      />
      {response?.type === 'error' && (
        <Text>{response.error?.description ?? 'Sign-in was rejected.'}</Text>
      )}
      {error && <Text>{error}</Text>}
    </View>
  );
}
```

The 2FA step (SMS, authenticator, or passkey) happens **inside the browser** on the EntryBit login page — the app does nothing special for it.

## Step 3 — Token rules (the two that matter)

- **Access token** lives ~15 minutes. Send it as `Authorization: Bearer <token>`. Treat it as opaque.
- **Refresh tokens rotate.** Every refresh returns a **new** `refresh_token` — always overwrite the stored one. Replaying an old one revokes the whole family (anti-theft) and returns `invalid_grant` → clear tokens and re-login.

Both rules live in one function. Note the **single-flight** guard: refresh tokens are single-use, so two parallel refreshes look like theft and revoke the whole family — concurrent callers must share one refresh.

`lib/session.ts`:

```ts
import * as AuthSession from 'expo-auth-session';
import { CLIENT_ID, getDiscovery } from './entrybit';
import { clearTokens, getFreshAccessToken, getRefreshToken, saveTokens } from './tokenStore';

/** Thrown when no session is left — route to the sign-in screen. */
export class SignedOutError extends Error {
  constructor() {
    super('Signed out');
    this.name = 'SignedOutError';
  }
}

let refreshInFlight: Promise<string> | null = null;

/** Returns a valid access token, refreshing if needed. Safe to call from anywhere. */
export async function getAccessToken({ forceRefresh = false } = {}): Promise<string> {
  if (!forceRefresh) {
    const fresh = getFreshAccessToken();
    if (fresh) return fresh;
  }
  refreshInFlight ??= refresh().finally(() => {
    refreshInFlight = null;
  });
  return refreshInFlight;
}

async function refresh(): Promise<string> {
  const refreshToken = await getRefreshToken();
  if (!refreshToken) throw new SignedOutError();

  try {
    const tokens = await AuthSession.refreshAsync(
      { clientId: CLIENT_ID, refreshToken },
      await getDiscovery(),
    );
    await saveTokens(tokens); // persists the ROTATED refresh token
    return tokens.accessToken;
  } catch (err) {
    if (err instanceof AuthSession.TokenError && err.code === 'invalid_grant') {
      // Expired, revoked, or reuse-detected — the session is over.
      await clearTokens();
      throw new SignedOutError();
    }
    throw err; // network blip — keep the tokens and let the caller retry
  }
}
```

Catch `SignedOutError` at your navigation layer and show the sign-in screen. See the [Token endpoint](/docs/oauth/token/) for the full rotation and reuse-detection contract.

## Step 4 — Call the API

All under `https://entrybit.net`, all `Authorization: Bearer <access_token>`, all JSON. Full schemas are in the [API reference](/docs/api-reference/passes/).

| Call | Scope | What it does |
|---|---|---|
| `GET /api/oauth/userinfo` | `openid` | Who is signed in (`sub`, `email`, `name`, `picture`) |
| `GET /api/v1/passes?limit&cursor&search` | `passes:read` | The user's guest passes, newest first. Page shape: `{ items, total, next_cursor, has_more, usage }` — `usage` is their monthly invite allowance |
| `POST /api/v1/passes` | `passes:write` | Create 1–10 passes → `201 { public_id, qr_values, pass_link, qr_sent, sms_sent }` |
| `GET /api/v1/passes/{public_id}` | `passes:read` | One pass (status: `expected → registered → checked_in → checked_out`, or `cancelled`) |
| `DELETE /api/v1/passes/{public_id}` | `passes:write` | Revoke an active pass (kills its QR on the doors too) |
| `GET /api/v1/invites` | `invites:read` | Org invitations addressed to the user |

A thin wrapper gives every call the Bearer header and the one retry that is safe — refresh-and-retry on `401`.

`lib/api.ts`:

```ts
import { getAccessToken } from './session';

const BASE_URL = 'https://entrybit.net';

export class ApiError extends Error {
  constructor(
    readonly status: number,
    readonly code: string,  // machine-readable — branch on this
    message: string,        // human-readable — display only
    readonly body: unknown, // full payload (e.g. 402 quota details)
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

export async function api<T>(path: string, init: RequestInit = {}): Promise<T> {
  let res = await send(path, init, await getAccessToken());

  if (res.status === 401) {
    // The token died early (e.g. revoked) — refresh once, retry once.
    res = await send(path, init, await getAccessToken({ forceRefresh: true }));
  }
  if (!res.ok) {
    const body = (await res.json().catch(() => ({}))) as {
      code?: string; error?: string; message?: string;
    };
    throw new ApiError(
      res.status,
      body.code ?? body.error ?? String(res.status),
      body.message ?? body.error ?? `HTTP ${res.status}`,
      body,
    );
  }
  return res.json() as Promise<T>;
}

function send(path: string, init: RequestInit, token: string): Promise<Response> {
  return fetch(`${BASE_URL}${path}`, {
    ...init,
    headers: {
      Accept: 'application/json',
      ...(init.body ? { 'Content-Type': 'application/json' } : {}),
      ...init.headers,
      Authorization: `Bearer ${token}`,
    },
  });
}
```

Using it — list the user's passes, then create one (full shapes in the [API reference](/docs/api-reference/passes/)):

```ts
import { api } from '../lib/api';

type PassPage = {
  items: Array<{ public_id: string; first_name: string; status: string; arrival_date: string }>;
  next_cursor: string | null;
  has_more: boolean;
};

const page = await api<PassPage>('/api/v1/passes?limit=30');

const created = await api<{ public_id: string; pass_link: string | null; qr_sent: boolean }>(
  '/api/v1/passes',
  {
    method: 'POST',
    body: JSON.stringify({
      first_name: 'Dana',
      email: 'dana@example.com',
      arrival_date: '2026-07-12',
      arrival_time: '14:30',
      facility_id: 42,
      quantity: 1,
    }),
  },
);
console.log(created.pass_link); // one shareable link — the QR is already emailed
```

The same call from a terminal, with an access token exported as `$ACCESS_TOKEN`:

```bash
curl -X POST https://entrybit.net/api/v1/passes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Dana",
    "email": "dana@example.com",
    "arrival_date": "2026-07-12",
    "arrival_time": "14:30",
    "facility_id": 42,
    "quantity": 1
  }'
```

Pagination: pass the previous page's `next_cursor` back as `cursor` until `has_more` is `false` — a ready-made loop is in [Conventions](/docs/api-reference/conventions/).

## Step 5 — Errors, branch on the code

| Status / `error` | Meaning | App behavior |
|---|---|---|
| `401 invalid_token` | Access token expired or invalid | Refresh, retry once; if refresh fails → re-login |
| `400 invalid_grant` (token endpoint) | Code/refresh expired, reused, or mismatched | Clear tokens → re-login |
| `403 insufficient_scope` | Token lacks the scope, or the user's org role was removed | Don't retry; show "not available for your account" |
| `402` (create pass) | Monthly invite allowance exhausted — body has `limit` / `current` | Show the quota message |
| `400 / 404 / 409` (create/revoke) | Validation / not found / pass no longer active | Show the message from the body |
| `429` | Rate limited | Back off and retry |

Error text is deliberately generic — **branch on the code, never parse the prose**. Full catalog: [Errors](/docs/api-reference/errors/).

## Step 6 — Logout

`lib/signOut.ts` — revoke the grant, forget the tokens, and (on shared devices) end the browser session too:

```ts
import * as AuthSession from 'expo-auth-session';
import * as WebBrowser from 'expo-web-browser';
import { CLIENT_ID, getDiscovery, redirectUri } from './entrybit';
import { clearTokens, getIdToken, getRefreshToken } from './tokenStore';

export async function signOut({ endBrowserSession = false } = {}): Promise<void> {
  const [discovery, refreshToken, idToken] = await Promise.all([
    getDiscovery(),
    getRefreshToken(),
    getIdToken(),
  ]);

  // 1. Revoke the grant — kills the whole rotating refresh-token family.
  //    Best-effort: local sign-out must still complete offline.
  if (refreshToken) {
    await AuthSession.revokeAsync(
      {
        token: refreshToken,
        clientId: CLIENT_ID,
        tokenTypeHint: AuthSession.TokenTypeHint.RefreshToken,
      },
      discovery,
    ).catch(() => {});
  }

  // 2. Forget everything locally.
  await clearTokens();

  // 3. Shared device? Also end the EntryBit browser session, so the next
  //    /authorize re-prompts for credentials instead of reusing the cookie.
  if (endBrowserSession && idToken && discovery.endSessionEndpoint) {
    const logoutUrl = `${discovery.endSessionEndpoint}?${new URLSearchParams({
      id_token_hint: idToken,
      post_logout_redirect_uri: redirectUri, // must be registered as a post-logout URI
    })}`;
    await WebBrowser.openAuthSessionAsync(logoutUrl, redirectUri);
  }
}
```

Alternatively, skip step 3 entirely by signing in with `promptAsync({ preferEphemeralSession: true })` (iOS) so no browser cookie ever persists.

RP-initiated logout only terminates the browser session when the `id_token_hint` verifies and matches the signed-in user, and only redirects to a **registered** post-logout URI. See [Logout](/docs/oauth/logout/).

## Nice-to-knows

- The `id_token` carries **`amr`** — *how* the user signed in (`["swk","user"]` = passkey, `["pwd","otp","mfa"]` = password + code, `["fed"]` = Google) — and `auth_time`. For a sensitive screen, request a fresh login with `prompt=login` (or `max_age=300`). See [ID token & UserInfo](/docs/oauth/id-token-userinfo/).
- The authorize redirect also carries **`iss`** ([RFC 9207](https://www.rfc-editor.org/rfc/rfc9207)) — your library may verify it automatically; safe to ignore otherwise.
- Server-to-server work (a backend acting for the whole organization) uses **API keys** on [`/api/v1/org/*`](/docs/api-reference/organization/) — not the mobile app's concern, but know it exists.

## Ship checklist

- [ ] Public client registered with the exact redirect URI; `scheme` set in `app.json`
- [ ] System browser via `expo-auth-session` (no WebView), PKCE on
- [ ] Refresh/id tokens only in SecureStore, access token in memory; the rotated refresh token overwritten on every refresh
- [ ] Refresh is single-flight — concurrent callers share one refresh, never two in parallel
- [ ] `invalid_grant` on refresh → clear tokens → login screen
- [ ] `401` → one refresh-and-retry; `403` / `402` → user-facing message
- [ ] Logout revokes the refresh token; ephemeral session on shared devices



# OAuth 2.0 & OpenID Connect

## OAuth 2.0 & OpenID Connect

Source: https://entrybit.net/docs/oauth/overview/

EntryBit is a full OAuth 2.0 authorization server and OpenID Connect provider — authorization-code flow with PKCE (S256) required for every client. The model, the flow, and the tokens you get.

EntryBit is a full **OAuth 2.0 authorization server** and **OpenID Connect provider**. Apps that sign users in — mobile apps, SPAs, server-rendered web apps — use the **authorization-code flow with PKCE**. There is no implicit grant, no password grant, and no `plain` PKCE: **PKCE S256 is mandatory for every client**, public or confidential.

- **Issuer:** `https://entrybit.net`
- **Discovery:** `GET /.well-known/openid-configuration` — most OIDC libraries configure themselves from this one URL
- **Signing:** RS256; public keys at [`/.well-known/jwks.json`](/docs/oauth/discovery-jwks/)

## Why authorization-code + PKCE

The authorization code flow keeps tokens off the front channel: the browser only ever carries a short-lived, single-use **code**, which your app exchanges for tokens over a direct back-channel call. **PKCE** ([RFC 7636](https://www.rfc-editor.org/rfc/rfc7636)) binds that code to a per-request secret (`code_verifier`) that only your app holds — so even if a hostile app on the device intercepts the redirected code, it cannot exchange it. This is why a public client (a mobile app or SPA with no secret) is safe: **PKCE replaces the client secret.**

## The flow, step by step

1. **Discover.** Fetch `/.well-known/openid-configuration` to find the authorize, token, userinfo, and logout endpoints.
2. **Generate PKCE.** Create a random `code_verifier`, then `code_challenge = BASE64URL(SHA-256(code_verifier))`.
3. **Authorize.** Open [`GET /api/oauth/authorize`](/docs/oauth/authorize/) in the **system browser** with `response_type=code`, your `client_id`, `redirect_uri`, `scope`, `state`, `code_challenge`, and `code_challenge_method=S256`.
4. **User signs in.** EntryBit runs login (password, passkey, Google, 2FA) and the consent screen — all inside the browser. Your app never sees the password.
5. **Redirect back.** On success the browser is 302-redirected to your `redirect_uri` with `code`, `state`, and **`iss`** ([RFC 9207](https://www.rfc-editor.org/rfc/rfc9207)).
6. **Exchange the code.** Call [`POST /api/oauth/token`](/docs/oauth/token/) with `grant_type=authorization_code`, the `code`, the same `redirect_uri`, your `client_id`, and the `code_verifier`.
7. **Get tokens.** Receive an access token (always), plus an `id_token` (with `openid`) and a `refresh_token` (with `offline_access`).
8. **Call the API.** Send `Authorization: Bearer <access_token>` to [`/api/v1/*`](/docs/api-reference/passes/).
9. **Refresh.** When the access token nears expiry, exchange the rotating refresh token for a fresh pair.

```
 App                     System Browser                EntryBit
  │  authorize (S256) ──────►│───────────────────────────►│  login + 2FA + consent
  │                          │◄───────────────────────────│  302 → redirect_uri?code&state&iss
  │◄─────────────────────────│  deep link back
  │  token (code + verifier) ───────────────────────────► │
  │◄──────────────────  { access_token, refresh_token?, id_token? }
  │  GET /api/v1/*  (Bearer access_token) ──────────────► │
```

## What you get back

| Token | Format | Lifetime | Purpose |
|---|---|---|---|
| **access_token** | RS256 JWT (`typ: at+jwt`) | ~15 min | Call `/api/v1/*` and `/api/oauth/userinfo`. `aud` = your `client_id`. |
| **id_token** | RS256 JWT (`typ: JWT`) | — | *Who* signed in and *how* (`sub`, `amr`, `auth_time`, identity claims). Issued with `openid`. |
| **refresh_token** | Opaque, rotating | 60 days | Obtain fresh access tokens without re-prompting. Issued with `offline_access`. |

Access tokens and id_tokens verify **offline** against the [JWKS](/docs/oauth/discovery-jwks/); refresh tokens are opaque and single-use — they **rotate** on every exchange, so always persist the newest.

## Client types

- **Public** (mobile apps, SPAs) — no secret. PKCE is the proof. This is the common case.
- **Confidential** (web apps with a secure backend) — a `client_secret` in addition to PKCE, enabling [Introspection](/docs/oauth/introspection-revocation/).

Register either in **Settings → Team → OAuth apps**. See [Register an app](/docs/oauth/register-an-app/).

## Endpoint reference

| Page | Endpoint |
|---|---|
| [Register an app](/docs/oauth/register-an-app/) | Self-service client registration |
| [Scopes](/docs/oauth/scopes/) | What you can request at consent |
| [Authorize endpoint](/docs/oauth/authorize/) | `GET /api/oauth/authorize` |
| [Token endpoint](/docs/oauth/token/) | `POST /api/oauth/token` |
| [ID token & UserInfo](/docs/oauth/id-token-userinfo/) | `id_token` claims + `GET\|POST /api/oauth/userinfo` |
| [Introspection & Revocation](/docs/oauth/introspection-revocation/) | `POST /api/oauth/introspect` · `POST /api/oauth/revoke` |
| [Logout](/docs/oauth/logout/) | `GET\|POST /api/oauth/logout` |
| [Discovery & JWKS](/docs/oauth/discovery-jwks/) | `/.well-known/*` |

Building a mobile app? Jump straight to the [Quickstart](/docs/get-started/quickstart-react-native/).


## Register an app

Source: https://entrybit.net/docs/oauth/register-an-app/

Self-service OAuth client registration in Settings → Team → OAuth apps: public vs confidential clients, the redirect-URI rules, post-logout URIs, scopes, and the one-time client secret.

Before an app can sign users in, it needs a **client** — a registration that tells EntryBit its name, its allowed redirect URIs, and the scopes it may request. Registration is **self-service**: any org admin can create a client in **Settings → Team → OAuth apps**, no support ticket required.

Clients are strictly **tenant-scoped**: a client is created under your organization, and only your organization can list, view, or delete it. Self-registered clients are marked **unverified** — the consent screen flags them as third-party apps. Each organization can have up to **50 active clients**.

## Public vs confidential

Choose the client type by whether the app can keep a secret:

| | Public | Confidential |
|---|---|---|
| For | Mobile apps, SPAs | Web apps with a secure backend |
| Client secret | **None** | Issued **once** at creation |
| Proof of identity | PKCE only | PKCE **+** `client_secret` |
| Can introspect tokens | No | Yes ([Introspection](/docs/oauth/introspection-revocation/)) |

**PKCE (S256) is required for both.** A public client is safe without a secret because PKCE binds each authorization code to a per-request verifier only the app holds. A confidential client adds a secret on top, which unlocks token introspection.

> Not sure which? A phone app or a browser-only SPA **cannot** keep a secret — register it as **public**. Only register **confidential** if the credential lives on a server you control.

## Registration fields

In **Settings → Team → OAuth apps → Register**, provide:

| Field | Required | Notes |
|---|---|---|
| `client_name` | ✓ | Shown on the consent screen. |
| `client_type` | ✓ | `public` or `confidential`. |
| `redirect_uris` | ✓ | One or more exact callback URIs (see rules below). |
| `post_logout_redirect_uris` |  | Where the browser may land after [logout](/docs/oauth/logout/). |
| `scopes` |  | The scopes this client may request (see [Scopes](/docs/oauth/scopes/)). |
| `logo_uri` |  | Displayed on the consent screen. |
| `client_uri` |  | Your app's homepage, linked from consent. |

On success you receive a `client_id`. For a **confidential** client you also receive a `client_secret` **exactly once** — store it immediately (it is SHA-256 hashed server-side and can never be retrieved again).

```json
{
  "success": true,
  "client_id": "eb_9f1c2ab34cd56ef7",
  "client_secret": null,
  "client_type": "public",
  "token_endpoint_auth_method": "none",
  "redirect_uris": ["entrybitresident://oauth/callback"],
  "allowed_scopes": "openid profile email offline_access passes:read"
}
```

> **`client_id` is public.** It ships in your app config and appears in every authorize request — that is by design. Only a confidential client's `client_secret` is sensitive. See [Authentication](/docs/get-started/authentication/) for the `client_id` vs `eb_sk_…` distinction.

## Redirect-URI rules

The redirect URI is where the browser hands the authorization code back to your app. EntryBit matches it **byte-for-byte** against your registered list — this is the open-redirect guard, so the rules are strict:

- **Exact match, no wildcards.** The request's `redirect_uri` must equal a registered one character-for-character.
- **No fragments.** A `#…` fragment is rejected.
- **Absolute URIs only.**
- **Web:** `https` is required (`http://localhost` is allowed for development).
- **Native:** a custom scheme such as `entrybitresident://oauth/callback` is allowed. A custom scheme is not OS-guaranteed unique — **PKCE is what protects you**: a hostile app that registers the same scheme still cannot exchange the intercepted code without your `code_verifier`. For the strongest binding, use a claimed `https` deep link (iOS Universal Link / Android App Link) if you can host the domain-association files.

`post_logout_redirect_uris` follow the same exact-match rules and are kept in a **separate list** from login redirect URIs.

## After registration

- Ship the `client_id` in your app and follow the [OAuth flow](/docs/oauth/overview/) (or the [React Native quickstart](/docs/get-started/quickstart-react-native/)).
- Users can see and revoke your app anytime under **Settings → Connected apps**; revoking there drops the stored consent and every refresh token the app holds for that user.
- To retire a client, delete it in **Settings → Team → OAuth apps** — it deactivates immediately and frees a slot against the 50-client cap.

Registering an app is different from minting an [API key](/docs/api-keys/overview/) (**Settings → API keys**): a client signs *users* in; an API key acts as the *organization*.


## Scopes

Source: https://entrybit.net/docs/oauth/scopes/

The permissions a token carries. User-consent scopes (openid, profile, email, offline_access, passes:*, invites:read) for OAuth apps, and org:* scopes for organization API keys.

A **scope** is a permission a credential carries. Two disjoint sets exist, one per authentication model: **user-consent scopes** that a signed-in user grants to an OAuth app, and **organization scopes** that an admin assigns to an [API key](/docs/api-keys/overview/). Always request the **least privilege** the integration needs.

## User-delegated scopes (OAuth consent)

Request these in the `scope` parameter of the [authorize request](/docs/oauth/authorize/), space-delimited. They must be a subset of the client's allowed scopes, and the user approves them on the consent screen. If you omit `scope`, the default is `openid profile email`.

| Scope | Grants |
|---|---|
| `openid` | Identity: the `sub` claim, an [`id_token`](/docs/oauth/id-token-userinfo/), and access to [UserInfo](/docs/oauth/id-token-userinfo/). Required for OIDC. |
| `profile` | The `name` and `picture` claims. |
| `email` | The `email` and `email_verified` claims. |
| `offline_access` | A rotating [refresh token](/docs/oauth/token/), so you can obtain fresh access tokens without re-prompting. |
| `passes:read` | View the user's guest passes ([`GET /api/v1/passes`](/docs/api-reference/passes/)). |
| `passes:write` | Create and revoke the user's guest passes ([`POST` / `DELETE /api/v1/passes`](/docs/api-reference/passes/)). |
| `invites:read` | View organization invitations addressed to the user ([`GET /api/v1/invites`](/docs/api-reference/invitations/)). |

A typical resident-app request:

```
openid profile email offline_access passes:read passes:write invites:read
```

Consent is remembered per user, client, and scope: requesting the same or a narrower set stays silent, while requesting a **superset** re-prompts. Send `prompt=consent` to force the consent screen every time.

## Organization API-key scopes

These are assigned when an admin mints an [API key](/docs/api-keys/create-and-manage/) in **Settings → API keys**. They act across the **whole organization**, not on behalf of a single user, and gate the [`/api/v1/org/*`](/docs/api-reference/organization/) endpoints.

| Scope | Grants |
|---|---|
| `org:passes:read` | Read every pass in the organization ([`GET /api/v1/org/passes`](/docs/api-reference/organization/)). |
| `org:passes:write` | Create and revoke any pass in the organization ([`POST` / `DELETE /api/v1/org/passes`](/docs/api-reference/organization/)). |
| `org:facilities:read` | List the organization's facilities ([`GET /api/v1/org/facilities`](/docs/api-reference/organization/)). |

## Enforcement

Scopes are checked on every request. A token that lacks a required scope is rejected with **`403 insufficient_scope`**, and the `WWW-Authenticate: Bearer` response header names the scope that was missing:

```http
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="passes:write"
```

For user-delegated calls, the acting user must **also** still hold the underlying organization role — a revoked resident cannot keep acting through an old grant, even if the token's scope is intact. See [Errors](/docs/api-reference/errors/) for how to react.


## Authorize endpoint

Source: https://entrybit.net/docs/oauth/authorize/

GET /api/oauth/authorize — begin the authorization-code flow. Parameters, the iss response parameter (RFC 9207), prompt and max_age, error redirects, and the open-redirect guard.

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](https://www.rfc-editor.org/rfc/rfc8252), never a WebView). EntryBit runs login and consent, then 302-redirects back to your app with a one-time code.

```http
GET /api/oauth/authorize
```

## Parameters

Passed as query parameters.

| Parameter | Required | Notes |
|---|---|---|
| `response_type` | ✓ | `code` only. |
| `client_id` | ✓ | Your registered client. |
| `redirect_uri` | ✓ | **Byte-exact** match against the client's registered allowlist. |
| `code_challenge` | ✓ | `BASE64URL(SHA-256(code_verifier))` — PKCE, always. |
| `code_challenge_method` | ✓ | `S256`. `plain` is rejected. |
| `scope` |  | Space-delimited subset of the client's allowed scopes. Default: `openid profile email`. See [Scopes](/docs/oauth/scopes/). |
| `state` | recommended | Opaque CSRF value, echoed back verbatim. |
| `nonce` | recommended | Binds the `id_token` to this request. Required if you validate id_tokens client-side. |
| `prompt` |  | Space-set of `none`, `login`, `consent`. |
| `max_age` |  | Maximum seconds since the user last authenticated. |

## 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](/docs/get-started/quickstart-react-native/). 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](/docs/oauth/id-token-userinfo/).

## Success response

On success EntryBit issues a 302 redirect to your `redirect_uri`:

```http
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](/docs/oauth/token/).

### The `iss` parameter (RFC 9207)

Every authorization response — **success and error** — carries `iss=https://entrybit.net` ([RFC 9207](https://www.rfc-editor.org/rfc/rfc9207), 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
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](/docs/api-reference/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](/docs/oauth/token/).


## Token endpoint

Source: https://entrybit.net/docs/oauth/token/

POST /api/oauth/token — exchange an authorization code for tokens, or refresh them. Both grants, the request and response shapes, refresh-token rotation, and family revocation on replay.

The token endpoint mints tokens. It handles two grants: **`authorization_code`** (exchange the code from [`/authorize`](/docs/oauth/authorize/)) and **`refresh_token`** (rotate an expiring session). It is a machine endpoint — **CSRF-exempt and CORS-open (`*`)**, because it carries client credentials and PKCE proofs, never cookies.

```http
POST /api/oauth/token
Content-Type: application/x-www-form-urlencoded
```

Send `application/x-www-form-urlencoded` (JSON is also accepted). Client authentication is `client_secret_basic` (HTTP Basic), `client_secret_post` (secret in the body), or `none` for public clients — where PKCE is the proof.

## Grant: `authorization_code`

Exchange the one-time code for tokens.

### Request

| Field | Required | Notes |
|---|---|---|
| `grant_type` | ✓ | `authorization_code` |
| `code` | ✓ | The code from the redirect (60-second TTL, single use). |
| `redirect_uri` | ✓ | Must equal the authorize request's `redirect_uri` byte-for-byte. |
| `code_verifier` | ✓ | The PKCE verifier (43–128 chars) whose S256 hash was sent to `/authorize`. |
| `client_id` | ✓ | Your client. |
| `client_secret` |  | Confidential clients only (or use HTTP Basic). |

```bash
# --data-urlencode form-encodes each value safely (redirect URIs carry reserved characters)
curl -X POST https://entrybit.net/api/oauth/token \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=SplxlOBeZQQYbYS6WxSbIA" \
  --data-urlencode "redirect_uri=entrybitresident://oauth/callback" \
  --data-urlencode "client_id=eb_9f1c2ab34cd56ef7" \
  --data-urlencode "code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
```

### Response

```json
{
  "access_token": "<RS256 JWT>",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "openid profile email offline_access passes:read",
  "refresh_token": "<opaque>",
  "id_token": "<RS256 JWT>"
}
```

`Cache-Control: no-store` is set on every token response. The `id_token` is present when `openid` was granted; the `refresh_token` is present when `offline_access` was granted.

> **Auth-code-injection defense:** a **replayed** authorization code revokes the entire refresh-token family it originally minted. Never exchange a code twice.

## Grant: `refresh_token`

Exchange the current refresh token for a fresh set — with a **new refresh token**.

### Request

| Field | Required | Notes |
|---|---|---|
| `grant_type` | ✓ | `refresh_token` |
| `refresh_token` | ✓ | The **current** refresh token (they rotate on every use). |
| `client_id` | ✓ | Your client. |
| `client_secret` |  | Confidential clients only (or use HTTP Basic). |
| `scope` |  | Optional **narrowing** of the granted scope — never widening. |

```bash
# A refresh token is a live credential — keep it in your secret store, not the command line
curl -X POST https://entrybit.net/api/oauth/token \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "refresh_token=$REFRESH_TOKEN" \
  --data-urlencode "client_id=eb_9f1c2ab34cd56ef7"
```

The response has the same shape as the authorization-code grant — **including a brand-new `refresh_token`**.

## Refresh-token rotation (read this)

Refresh tokens are **opaque, single-use, and rotate on every exchange**. The rules that keep a session healthy:

- **Always persist the newest `refresh_token`** returned by each refresh. The old one is now dead.
- **Never keep two copies, and never refresh the same token twice concurrently.** Presenting a superseded or revoked token is treated as theft: EntryBit revokes the **entire token family** (the stolen-token kill switch) and returns a generic `invalid_grant`.
- On `invalid_grant`, **clear your tokens and send the user to log in again.**

In code, the contract is an ordering — persist the new refresh token *before* the new access token is used, and keep at most one refresh in flight:

```ts
// Sketch — a complete client (single-flight + invalid_grant handling) is in
// the React Native quickstart's lib/session.ts.
const tokens = await postTokenRefresh(stored.refreshToken); // ONE at a time, app-wide

await secureStore.set('refreshToken', tokens.refresh_token); // 1. the old token is dead
authorizeWith(tokens.access_token);                          // 2. only then use the new pair
```

Refresh tokens live **60 days**; access tokens live **~15 minutes**. Access tokens are stateless JWTs — they simply expire and cannot be revoked individually (revoke the refresh token to end a session; see [Revocation](/docs/oauth/introspection-revocation/)).

## The tokens

| Token | Format | Lifetime | Claims / notes |
|---|---|---|---|
| **access_token** | RS256 JWT, `typ: at+jwt` ([RFC 9068](https://www.rfc-editor.org/rfc/rfc9068)) | ~15 min | `iss sub aud client_id scope iat nbf exp jti`; `aud` = your `client_id`. |
| **id_token** | RS256 JWT, `typ: JWT` | — | `iss sub aud iat exp` + `nonce? auth_time? amr? at_hash?` + scope-gated identity. See [ID token & UserInfo](/docs/oauth/id-token-userinfo/). |
| **refresh_token** | Opaque, SHA-256 stored | 60 days | Single-use, rotating. |

Both JWTs verify **offline** against the [JWKS](/docs/oauth/discovery-jwks/).

## Errors

| Status | `error` | Meaning |
|---|---|---|
| `400` | `invalid_grant` | Code/refresh expired, reused, mismatched, or family-revoked. |
| `400` | `invalid_request` | A required parameter is missing or malformed. |
| `400` | `invalid_scope` | Requested a scope the client (or grant) doesn't allow. |
| `400` | `unsupported_grant_type` | `grant_type` is not `authorization_code` or `refresh_token`. |
| `401` | `invalid_client` | Client authentication failed. |
| `429` | `temporarily_unavailable` | Rate limited — back off and retry. |

Descriptions are deliberately generic (no token-state oracle). Branch on the `error` code — see [Errors](/docs/api-reference/errors/).


## ID token & UserInfo

Source: https://entrybit.net/docs/oauth/id-token-userinfo/

The id_token claims — including amr (how the user authenticated) and auth_time — and the UserInfo endpoint (GET|POST /api/oauth/userinfo) that returns scope-gated identity claims.

OpenID Connect gives you two sources of identity: the **`id_token`** returned by the [token endpoint](/docs/oauth/token/) (a signed statement about *who* signed in and *how*), and the **UserInfo endpoint** (a live, server-verified lookup of the user's claims). Both are gated by the scopes the user granted.

## The `id_token`

Issued when the `openid` scope is granted. It is an **RS256 JWT** (`typ: JWT`) that verifies offline against the [JWKS](/docs/oauth/discovery-jwks/).

### Claims

| Claim | Always | Meaning |
|---|---|---|
| `iss` | ✓ | Issuer — `https://entrybit.net`. |
| `sub` | ✓ | Stable EntryBit user identifier. |
| `aud` | ✓ | Your `client_id`. |
| `iat` | ✓ | Issued-at (Unix seconds). |
| `exp` | ✓ | Expiry (Unix seconds). |
| `nonce` |  | Echoed from your authorize request — verify it matches. |
| `auth_time` |  | When the user actually authenticated (Unix seconds). |
| `amr` |  | **How** the user authenticated (see below). |
| `at_hash` |  | Binds the id_token to the access token. |
| `email`, `email_verified` |  | With the `email` scope. |
| `name`, `picture` |  | With the `profile` scope. |

### `amr` — how the user signed in

The `amr` (Authentication Methods References, [RFC 8176](https://www.rfc-editor.org/rfc/rfc8176)) array records the factors used at login. EntryBit stamps these values:

| Value | Meaning |
|---|---|
| `pwd` | Password. |
| `otp` | One-time code (authenticator / email). |
| `sms` | SMS one-time code. |
| `swk` | Passkey (software-backed key). |
| `user` | Passkey with user verification. |
| `fed` | Federated login (Google). |
| `mfa` | Two or more factors were used. |

For example, `["swk","user"]` is a verified passkey, `["pwd","otp","mfa"]` is password plus a code, and `["fed"]` is Google. Combined with `auth_time`, this lets a sensitive screen require a *recent* or *stronger* login — request one with `prompt=login` or `max_age` on the [authorize request](/docs/oauth/authorize/).

### Validating it yourself

If you decode the `id_token` on the client, **fully validate the JWT** — do not trust decoded claims blindly:

1. Verify the **signature** against [`/.well-known/jwks.json`](/docs/oauth/discovery-jwks/).
2. Check `iss` == `https://entrybit.net`.
3. Check `aud` == your `client_id`.
4. Check `exp` is in the future.
5. Check `nonce` equals the value you sent (so **make `nonce` required** if you consume the id_token). Many libraries — including `expo-auth-session` — do **not** validate id_tokens for you.

With [`jose`](https://github.com/panva/jose) in Node.js, steps 1–4 are options and step 5 is yours:

```ts
// npm install jose
import { createRemoteJWKSet, jwtVerify } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://entrybit.net/.well-known/jwks.json'));

export async function verifyIdToken(idToken: string, expectedNonce: string) {
  // Steps 1–4 — signature, iss, aud, exp — enforced by jose.
  const { payload } = await jwtVerify(idToken, JWKS, {
    issuer: 'https://entrybit.net',
    audience: CLIENT_ID,
    algorithms: ['RS256'],
  });

  // Step 5 — the nonce binds this id_token to YOUR authorize request.
  if (payload.nonce !== expectedNonce) {
    throw new Error('id_token nonce mismatch — possible replay');
  }

  return payload; // { sub, amr?, auth_time?, email?, name?, … }
}
```

If you only need the user's profile, prefer UserInfo below — it is already server-verified.

## UserInfo endpoint

Returns the signed-in user's claims, gated by the granted scopes. Available over GET and POST (OIDC Core §5.3.1 — the two are identical).

```http
GET  /api/oauth/userinfo
POST /api/oauth/userinfo
Authorization: Bearer <access_token>
```

Requires the `openid` scope. The `email` and `profile` scopes gate their respective claims.

```bash
curl https://entrybit.net/api/oauth/userinfo \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Response

```json
{
  "sub": "usr_9f1c2ab34cd56ef7",
  "email": "dana@example.com",
  "email_verified": true,
  "name": "Dana Cohen",
  "picture": "https://entrybit.net/…"
}
```

| Field | Present when |
|---|---|
| `sub` | Always (with `openid`). |
| `email`, `email_verified` | The `email` scope was granted. |
| `name`, `picture` | The `profile` scope was granted. |

### Errors

`401`/`403` responses carry a `WWW-Authenticate: Bearer` challenge:

| Status | `error` | Meaning |
|---|---|---|
| `401` | `invalid_token` | Missing, expired, or invalid access token — [refresh](/docs/oauth/token/) or re-login. |
| `403` | `insufficient_scope` | The token lacks `openid`. |

See [Errors](/docs/api-reference/errors/) for the full Bearer-challenge contract.


## Introspection & Revocation

Source: https://entrybit.net/docs/oauth/introspection-revocation/

POST /api/oauth/introspect (RFC 7662, confidential clients, caller-bound) to check a token's state, and POST /api/oauth/revoke (RFC 7009) to kill a refresh-token family. Always returns 200.

Two machine endpoints for managing token state: **introspection** asks whether a token is active (for confidential resource servers), and **revocation** ends a session by killing a refresh-token family. Both are CSRF-exempt and cookie-free.

## Introspection

```http
POST /api/oauth/introspect
Content-Type: application/x-www-form-urlencoded
```

[RFC 7662](https://www.rfc-editor.org/rfc/rfc7662). A resource server looks up a token's current state. **Confidential clients only** — the caller authenticates with its `client_secret` (HTTP Basic or `client_secret_post`), because introspection is a token-state oracle that must not be exposed to public clients.

> Most integrations do **not** need this. EntryBit access tokens are self-contained RS256 JWTs you can verify **offline** against the [JWKS](/docs/oauth/discovery-jwks/) — no network round-trip. Introspection exists for confidential clients that prefer a live check or need to inspect opaque refresh tokens.

### Request

| Field | Required | Notes |
|---|---|---|
| `token` | ✓ | The access or refresh token to inspect. |
| `client_id` |  | Client credentials (or use HTTP Basic). |
| `client_secret` |  | Client credentials (or use HTTP Basic). |

```bash
# Client secret and token stay out of the command line — export them first
curl -X POST https://entrybit.net/api/oauth/introspect \
  -u "eb_9f1c2ab34cd56ef7:$ENTRYBIT_CLIENT_SECRET" \
  --data-urlencode "token=$TOKEN_TO_INSPECT"
```

### Response

An active token returns its metadata:

```json
{
  "active": true,
  "sub": "usr_9f1c2ab34cd56ef7",
  "scope": "openid profile email passes:read",
  "client_id": "eb_9f1c2ab34cd56ef7",
  "token_type": "Bearer",
  "iss": "https://entrybit.net",
  "aud": "eb_9f1c2ab34cd56ef7",
  "exp": 1752148800,
  "iat": 1752147900
}
```

Anything else — expired, revoked, unknown, or **belonging to another client** — returns the flat, indistinguishable:

```json
{ "active": false }
```

Lookups are **bound to the calling client**: a client can only introspect tokens issued to it, and the response never distinguishes *why* a token is inactive (no enumeration oracle). A failed client authentication returns `401 invalid_client`.

## Revocation

```http
POST /api/oauth/revoke
Content-Type: application/x-www-form-urlencoded
```

[RFC 7009](https://www.rfc-editor.org/rfc/rfc7009). Revoke a **refresh token** — and with it the whole rotation family it belongs to. This is how an app signs a user out (see [Logout](/docs/oauth/logout/) for ending the *browser* session too).

### Request

| Field | Required | Notes |
|---|---|---|
| `token` | ✓ | The refresh token to revoke. |
| `client_id` |  | Client credentials (public clients send `client_id`; confidential add the secret / Basic). |
| `client_secret` |  | Confidential clients only. |

```bash
curl -X POST https://entrybit.net/api/oauth/revoke \
  --data-urlencode "token=$REFRESH_TOKEN" \
  --data-urlencode "client_id=eb_9f1c2ab34cd56ef7"
```

### Response

**Always `200`** — even for an unknown token. The server never scans or confirms token existence, so revocation cannot be used to probe for valid tokens. When the token belongs to the caller, its **entire rotation family** is revoked; if it doesn't, the call still returns `200` and does nothing.

```http
HTTP/1.1 200 OK
```

> Access tokens are **stateless** and are not revoked here — they simply expire (~15 minutes). Revoke the refresh token to end the session; any outstanding access token dies on its own shortly after.


## Logout

Source: https://entrybit.net/docs/oauth/logout/

RP-initiated logout (GET|POST /api/oauth/logout) — end the user's EntryBit browser session with a verified id_token_hint, redirect to a registered post_logout_redirect_uri, and the forced-logout-CSRF defense.

RP-initiated logout ends the user's **EntryBit browser session** — the cookie the system browser holds after signing in. It is the OIDC `end_session_endpoint` ([OIDC RP-Initiated Logout 1.0](https://openid.net/specs/openid-connect-rpinitiated-1_0.html)), advertised in [discovery](/docs/oauth/discovery-jwks/).

```http
GET  /api/oauth/logout
POST /api/oauth/logout
```

> **Two different logouts.** [Revoking the refresh token](/docs/oauth/introspection-revocation/) signs *your app* out (kills its tokens). This endpoint signs the *browser session* out, so the next `/authorize` re-prompts for a password instead of silently reusing the cookie. On shared devices you want both.

## Parameters

GET takes query parameters; POST takes the same fields in an `application/x-www-form-urlencoded` body.

| Parameter | Notes |
|---|---|
| `id_token_hint` | The `id_token` previously issued to the client. Its signature must verify (it **may** be expired). Required to actually terminate the session. |
| `post_logout_redirect_uri` | Where to send the browser afterward — must **exactly** match the client's registered post-logout list. |
| `state` | Opaque value echoed to the post-logout redirect. |
| `client_id` | Optional; when present it must match the hint's audience. |

## Behavior

The session is terminated **only** when the `id_token_hint`:

1. **verifies** — valid signature and issuer (expiry is *not* required); and
2. **matches** — its `sub` equals the currently signed-in user.

Then the browser is redirected to `post_logout_redirect_uri` **only if** it exactly matches one of the client's registered `post_logout_redirect_uris` (a separate allowlist from login redirect URIs — register them in [Settings → Team → OAuth apps](/docs/oauth/register-an-app/)). When it matches, `state` is appended. With no hint, an invalid hint, or an unregistered URI, the browser simply lands on the EntryBit home page.

```http
HTTP/1.1 302 Found
Location: entrybitresident://oauth/callback?state=<same>
```

## The forced-logout-CSRF defense

The `id_token_hint` requirement is a security control, not a formality. Without it, a bare cross-site `GET /api/oauth/logout` embedded in any web page could **force-log-out** a signed-in user (a logout CSRF). By requiring a **verified `id_token_hint` whose `sub` matches the current user**, EntryBit ensures only a party that already holds the user's own id_token can end their session — an attacker cannot.

## In a native app

Take the endpoint from [discovery](/docs/oauth/discovery-jwks/) (`end_session_endpoint`) rather than hardcoding the path:

```ts
import * as AuthSession from 'expo-auth-session';
import * as WebBrowser from 'expo-web-browser';

const { endSessionEndpoint } = await AuthSession.fetchDiscoveryAsync('https://entrybit.net');
if (!endSessionEndpoint) throw new Error('end_session_endpoint not advertised');

const logoutUrl = `${endSessionEndpoint}?${new URLSearchParams({
  id_token_hint: idToken,                // the id_token from sign-in
  post_logout_redirect_uri: redirectUri, // must be REGISTERED as a post-logout URI
})}`;

await WebBrowser.openAuthSessionAsync(logoutUrl, redirectUri);
```

The simplest alternative on shared devices is to sign in with an **ephemeral browser session** in the first place, so no cookie ever persists:

```ts
promptAsync({ preferEphemeralSession: true }); // iOS: no shared Safari cookies
```

A complete sign-out does both: [revoke the refresh token](/docs/oauth/introspection-revocation/), clear local storage, then hit this endpoint (or use an ephemeral session). See the [quickstart](/docs/get-started/quickstart-react-native/).


## Discovery & JWKS

Source: https://entrybit.net/docs/oauth/discovery-jwks/

The self-description documents: /.well-known/openid-configuration (OIDC Discovery + RFC 8414) and /.well-known/jwks.json (RS256 public keys). How to verify EntryBit tokens offline.

Everything about the authorization server self-describes at two public, unauthenticated URLs. Point an OIDC library at the discovery document and it configures every endpoint itself; point a JWT verifier at the JWKS and it can validate EntryBit tokens **offline**, with no round-trip to EntryBit.

## Discovery document

```http
GET /.well-known/openid-configuration     # OIDC Discovery 1.0
GET /.well-known/oauth-authorization-server   # RFC 8414 — identical body
```

Both URLs return the same metadata. OIDC libraries look at the first; [RFC 8414](https://www.rfc-editor.org/rfc/rfc8414) clients look at the second.

```bash
curl https://entrybit.net/.well-known/openid-configuration
```

Key fields:

| Field | Value / meaning |
|---|---|
| `issuer` | `https://entrybit.net` |
| `authorization_endpoint` | [`/api/oauth/authorize`](/docs/oauth/authorize/) |
| `token_endpoint` | [`/api/oauth/token`](/docs/oauth/token/) |
| `userinfo_endpoint` | [`/api/oauth/userinfo`](/docs/oauth/id-token-userinfo/) |
| `introspection_endpoint` | [`/api/oauth/introspect`](/docs/oauth/introspection-revocation/) |
| `revocation_endpoint` | [`/api/oauth/revoke`](/docs/oauth/introspection-revocation/) |
| `end_session_endpoint` | [`/api/oauth/logout`](/docs/oauth/logout/) |
| `jwks_uri` | `/.well-known/jwks.json` |
| `scopes_supported` | The full [scope](/docs/oauth/scopes/) catalog. |
| `response_types_supported` | `["code"]` |
| `code_challenge_methods_supported` | `["S256"]` — PKCE S256 only. |
| `subject_types_supported` | `["public"]` |
| `id_token_signing_alg_values_supported` | `["RS256"]` |
| `claims_supported` | Identity claims, plus `amr` and `auth_time`. |
| `authorization_response_iss_parameter_supported` | `true` ([RFC 9207](https://www.rfc-editor.org/rfc/rfc9207)). |

With `expo-auth-session`, `AuthSession.useAutoDiscovery('https://entrybit.net')` fetches this and wires up every endpoint — including logout — for you.

## JWKS

```http
GET /.well-known/jwks.json
```

The JSON Web Key Set: the RS256 **public** keys that verify access tokens and id_tokens. Each key's `kid` is its [RFC 7638](https://www.rfc-editor.org/rfc/rfc7638) thumbprint — match it against the JWT header's `kid` to pick the right key.

```json
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "alg": "RS256",
      "kid": "<RFC 7638 thumbprint>",
      "n": "<modulus>",
      "e": "AQAB"
    }
  ]
}
```

> **Deploy note:** these are backend routes, not static files. Behind a reverse proxy, `/.well-known/openid-configuration`, `/.well-known/oauth-authorization-server`, and `/.well-known/jwks.json` must all route to the EntryBit backend.

## Verifying a token offline

EntryBit access tokens are self-contained RS256 JWTs (`typ: at+jwt`), so a resource server can authorize a request without calling EntryBit at all:

1. **Fetch and cache** the JWKS. Refresh on an unknown `kid` (keys can rotate).
2. **Select the key** whose `kid` matches the token header's `kid`.
3. **Verify the signature** with that RSA public key.
4. **Check the claims:**
   - `iss` == `https://entrybit.net`
   - `exp` in the future (and `nbf` in the past)
   - `typ` == `at+jwt` (this gate blocks access-token / id-token confusion in both directions)
   - `aud` == the expected `client_id`, if you pin it
5. **Enforce `scope`** for the operation. See [Scopes](/docs/oauth/scopes/).

Use a maintained JWT library rather than hand-rolling RSA verification. In Node.js, [`jose`](https://github.com/panva/jose) covers steps 1–4 in a few lines:

```ts
// npm install jose
import { createRemoteJWKSet, jwtVerify } from 'jose';

const ISSUER = 'https://entrybit.net';

// Step 1 — fetched once, cached, and refetched automatically when a token
// arrives signed by an unknown kid (key rotation).
const JWKS = createRemoteJWKSet(new URL(`${ISSUER}/.well-known/jwks.json`));

export async function verifyAccessToken(token: string, requiredScope: string) {
  // Steps 2–4 — signature, iss, exp/nbf, and typ, all enforced by jose.
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: ISSUER,
    algorithms: ['RS256'],
    typ: 'at+jwt',                   // blocks an id_token posing as an access token
    audience: 'eb_9f1c2ab34cd56ef7', // your client_id — omit if you don't pin aud
  });

  // Step 5 — enforce scope for the operation.
  const scopes = typeof payload.scope === 'string' ? payload.scope.split(' ') : [];
  if (!scopes.includes(requiredScope)) {
    throw new Error(`missing scope: ${requiredScope}`); // respond 403 insufficient_scope
  }

  return payload; // { iss, sub, aud, client_id, scope, iat, nbf, exp, jti }
}
```

```ts
// In a request handler:
const claims = await verifyAccessToken(bearerToken, 'passes:read');
// claims.sub is the EntryBit user id — authorize the operation against it.
```

If you prefer a live check over local verification — or need to inspect an opaque refresh token — a confidential client can use [Introspection](/docs/oauth/introspection-revocation/) instead.



# API keys

## API keys

Source: https://entrybit.net/docs/api-keys/overview/

Organization API keys (eb_sk_…) authenticate servers and SDKs acting as the whole organization. Org-scoped, least-privilege, shown once — and why they're stored as SHA-256, not Argon2id.

An **organization API key** authenticates a server or SDK acting as the **whole organization** — not on behalf of any one signed-in user. It is the server-side counterpart to the user-facing [OAuth flow](/docs/oauth/overview/): where OAuth answers "which user is this?", an API key answers "which organization is this?".

- **Shape:** `eb_sk_…` — the `sk` means *secret key*.
- **Created in:** **Settings → API keys** by an org admin.
- **Scopes:** least-privilege [`org:*`](/docs/oauth/scopes/) permissions.
- **Calls:** [`/api/v1/org/*`](/docs/api-reference/organization/).

> **A key is a server secret — never ship it in an app.** An `eb_sk_…` key acts as your entire organization and can be extracted from any downloadable binary (APK, SPA bundle). Client apps use an OAuth [`client_id`](/docs/get-started/authentication/) (public, PKCE-protected) instead. If a key was ever embedded or shared, [revoke it](/docs/api-keys/create-and-manage/).

## What a key carries

Each key is minted with:

- **Least-privilege scopes** — pick only the `org:*` scopes the integration needs (`org:passes:read`, `org:passes:write`, `org:facilities:read`). See [Scopes](/docs/oauth/scopes/).
- **An optional expiry** — after which the key stops working.
- **An optional source-IP allowlist** — requests from other IPs are rejected.

The key is **shown exactly once**, at creation. EntryBit stores only its hash and can never display it again — if it's lost, revoke it and mint a new one. See [Create & manage keys](/docs/api-keys/create-and-manage/).

## Why keys are stored as SHA-256, not Argon2id

User passwords at EntryBit are hashed with **Argon2id**. API keys are hashed with plain **SHA-256** — and that is deliberate, not a shortcut.

An API key is **256 bits of CSPRNG output**. There is no dictionary, no pattern, no human-memorable structure — so an offline preimage or brute-force search against *any* hash is computationally infeasible. Argon2id exists to slow down guessing of **low-entropy** secrets (passwords people choose); it buys nothing against a full-entropy random key.

Meanwhile, a memory-hard KDF on the **hot, per-request verify path** would be actively harmful:

- **Latency** — every authenticated API call would pay Argon2's deliberate cost.
- **A DoS lever** — an attacker POSTing garbage keys would force expensive Argon2 work per request, turning the verification step into a CPU-exhaustion amplifier.

A fast hash is therefore the *correct* choice for high-entropy machine credentials — the same doctrine EntryBit applies to OAuth client secrets and refresh tokens. Argon2id for what humans choose; SHA-256 for what a CSPRNG generates.

## Keys vs OAuth, at a glance

| | API key | OAuth access token |
|---|---|---|
| Acts as | The organization | A signed-in user |
| Credential | `eb_sk_…` (long-lived secret) | JWT (~15 min, from a `client_id` + PKCE) |
| Endpoints | `/api/v1/org/*` | `/api/v1/*` |
| Scopes | `org:passes:*`, `org:facilities:read` | `passes:*`, `invites:read`, … |
| Lives | On your server, in a vault | In the app, refreshed as needed |

## Next steps

- [Create & manage keys](/docs/api-keys/create-and-manage/) — mint, reveal, and revoke.
- [Authenticating requests](/docs/api-keys/authenticating/) — how to send the key and the challenges you'll get.
- [Organization API](/docs/api-reference/organization/) — the endpoints keys can call.


## Create & manage keys

Source: https://entrybit.net/docs/api-keys/create-and-manage/

Mint an organization API key in Settings → API keys — name, scopes, optional expiry and IP allowlist — copy the one-time secret, and revoke keys you no longer need. Requires the org:api_keys permission.

Organization API keys are created and revoked in **Settings → API keys**. Both actions require the **`org:api_keys`** RBAC permission (held only by org admins) plus CSRF protection, and every mint and revoke is **audited**.

## Create a key

In **Settings → API keys → Create**, provide:

| Field | Required | Notes |
|---|---|---|
| **Name** | ✓ | A label to recognise the key later (e.g. "Nightly sync", "Partner SDK"). |
| **Scopes** | ✓ | The least-privilege [`org:*` scopes](/docs/oauth/scopes/) this key needs: `org:passes:read`, `org:passes:write`, `org:facilities:read`. |
| **Expiry** |  | Optional date after which the key stops working. Prefer setting one. |
| **IP allowlist** |  | Optional list of source IPs; requests from any other address are rejected. |

Grant only the scopes the integration actually uses. A data-export job needs `org:passes:read`; it does not need `org:passes:write`.

## Copy the secret — it's shown once

On creation the full key is returned **exactly once**:

```
eb_sk_live_9f1c2ab34cd56ef7a8b9c0d1e2f3a4b5
```

Copy it immediately into your secret manager. EntryBit stores only a [SHA-256 hash](/docs/api-keys/overview/) and **cannot show the key again** — if you lose it, revoke it and mint a replacement. Never commit a key to source control, paste it into a client app, or log it.

## Revoke a key

In **Settings → API keys**, revoke any key you no longer trust or need. Revocation takes effect immediately: the next request using that key is rejected with `401`. Revoke a key the moment it may have leaked, a teammate with access leaves, or an integration is retired.

Because minting and revoking both require `org:api_keys` + CSRF and are audited, you get an accountable trail of who created and killed each key.

## Rotation

To rotate without downtime:

1. **Mint** a new key with the same scopes.
2. **Deploy** it to your server / secret manager.
3. **Verify** traffic is flowing on the new key.
4. **Revoke** the old key.

Setting an **expiry** at creation turns rotation into a scheduled habit rather than an afterthought.

## Using the key

Once you have the secret, see [Authenticating requests](/docs/api-keys/authenticating/) for how to send it, and the [Organization API](/docs/api-reference/organization/) for the endpoints it can call.

> This page is about **API keys** (server secrets). Registering an app that signs *users* in is a different task — see [Register an app](/docs/oauth/register-an-app/) under **Settings → Team → OAuth apps**.


## Authenticating requests

Source: https://entrybit.net/docs/api-keys/authenticating/

Send an organization API key as Authorization: Bearer eb_sk_… (or X-API-Key), the 401/403 challenges you'll get, and the per-IP rate limit of 300 requests/minute.

Every request to the [Organization API](/docs/api-reference/organization/) authenticates with an [API key](/docs/api-keys/overview/). Send the key on each call — there is no session, no cookie, and no CSRF token; the key itself is the credential.

## Sending the key

Use the standard `Authorization: Bearer` header, with the key supplied by your environment or secret manager (the examples assume `ENTRYBIT_API_KEY` is set — never paste the literal key into a command line or source file):

```bash
curl https://entrybit.net/api/v1/org/facilities \
  -H "Authorization: Bearer $ENTRYBIT_API_KEY"
```

Or the `X-API-Key` header, if that's easier for your HTTP client:

```bash
curl https://entrybit.net/api/v1/org/facilities \
  -H "X-API-Key: $ENTRYBIT_API_KEY"
```

Both are equivalent. Always over TLS — **never put a key in a URL**, a query string, or a log line.

The same call from server-side code:

```ts
// Node.js 18+
const res = await fetch('https://entrybit.net/api/v1/org/facilities', {
  headers: { Authorization: `Bearer ${process.env.ENTRYBIT_API_KEY}` },
});
if (!res.ok) throw new Error(`EntryBit ${res.status}`); // 401/403/429 — see below
const { facilities } = await res.json();
```

```python
# Python
import os
import requests

res = requests.get(
    "https://entrybit.net/api/v1/org/facilities",
    headers={"Authorization": f"Bearer {os.environ['ENTRYBIT_API_KEY']}"},
    timeout=10,  # requests has no default timeout — always set one
)
res.raise_for_status()
facilities = res.json()["facilities"]
```

## Challenges

| Status | `error` | Meaning | What to do |
|---|---|---|---|
| `401` | `invalid_token` | Missing, unknown, revoked, expired, or IP-restricted key (indistinguishable by design). | Check the key and its expiry / IP allowlist; mint a new one if needed. |
| `403` | `insufficient_scope` | The key lacks a required [`org:*` scope](/docs/oauth/scopes/). | Mint a key with the needed scope — scopes are fixed at creation. |
| `429` | `temporarily_unavailable` | Rate limited. | Back off and retry. |

`401` and `403` carry a `WWW-Authenticate: Bearer` challenge; on `403` it names the missing scope:

```http
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="org:passes:write"
```

A `401` is **deliberately ambiguous** — an unknown key, a revoked key, an expired key, and a key used from a disallowed IP all look identical, so an attacker can't probe which of those is true. See [Errors](/docs/api-reference/errors/) for the full catalog.

## Rate limits

Organization API requests are rate-limited **per source IP** at **300 requests per minute**. Exceeding it returns `429` — back off (ideally with exponential backoff and jitter) and retry. This is a separate bucket from the per-user `120/min` limit on the [user-delegated API](/docs/api-reference/passes/).

## Scope enforcement

The key's scopes gate what it can do:

- `org:passes:read` → [`GET /api/v1/org/passes`](/docs/api-reference/organization/)
- `org:passes:write` → [`POST` / `DELETE /api/v1/org/passes`](/docs/api-reference/organization/)
- `org:facilities:read` → [`GET /api/v1/org/facilities`](/docs/api-reference/organization/)

A key acts only within its own organization — it can never read or modify another tenant's data, regardless of scope. Next: the [Organization API](/docs/api-reference/organization/) reference.



# API reference

## Conventions

Source: https://entrybit.net/docs/api-reference/conventions/

How the EntryBit REST API works across every endpoint: base URL, the two auth schemes, error envelopes, rate limits, and keyset pagination (limit / cursor / next_cursor / has_more / search).

Conventions that hold across every endpoint of the resource API. Read this once and the individual endpoint pages ([Passes](/docs/api-reference/passes/), [Invitations](/docs/api-reference/invitations/), [Organization](/docs/api-reference/organization/)) are just field lists.

## Base URL

```
https://entrybit.net
```

All traffic is JSON over HTTPS (TLS required). Credential-bearing responses set `Cache-Control: no-store`. Never place a credential in a URL.

## Authentication

Two schemes, depending on who is acting — see [Authentication](/docs/get-started/authentication/) for the full picture:

| Scheme | Header | Acts as | Endpoints |
|---|---|---|---|
| **OAuth access token** | `Authorization: Bearer <JWT>` | A signed-in user | `/api/v1/*` |
| **Organization API key** | `Authorization: Bearer eb_sk_…` (or `X-API-Key`) | The organization | `/api/v1/org/*` |

An access token is a short-lived RS256 JWT from the [token endpoint](/docs/oauth/token/); an API key is a long-lived secret from [Settings → API keys](/docs/api-keys/create-and-manage/).

## Error envelopes

EntryBit uses different error shapes for protocol vs business failures. In all of them, **branch on the code, never on the human-readable text** — descriptions are deliberately generic.

**Bearer challenges (RFC 6750)** — auth failures on any resource endpoint. A `WWW-Authenticate: Bearer` header accompanies the body:

```json
{ "error": "insufficient_scope" }
```

The `error` is `invalid_token` (`401`) or `insufficient_scope` (`403`).

**Business errors (`AppError`)** — validation, not-found, and conflict failures come in one of two equivalent shapes:

```json
{ "success": false, "error": "Facility not found" }
```
```json
{ "code": "…", "message": "Facility not found" }
```

Either form carries a machine-readable field (`error` or `code`) and a human-readable message; the exact `code` value depends on the endpoint.

**Quota (`402`)** — exhausting the monthly invite allowance returns a distinct shape:

```json
{
  "code": "CAPACITY_EXCEEDED",
  "message": "Monthly guest-invite allowance exceeded",
  "dimension": "guest_invites",
  "limit": 50,
  "current": 50,
  "requested": 3
}
```

The full mapping of status codes to reactions is in [Errors](/docs/api-reference/errors/).

## Rate limits

Per-credential and per-IP buckets; exceeding one returns `429` with `{ "error": "temporarily_unavailable" }`. Back off and retry (exponential backoff with jitter).

| API | Limit |
|---|---|
| User-delegated (`/api/v1/*`) | 120 requests / minute / user |
| Organization (`/api/v1/org/*`) | 300 requests / minute / source IP |

## Keyset pagination

List endpoints are **keyset (cursor) paginated**, newest first — stable and efficient even as rows are added underneath you.

**Query parameters:**

| Parameter | Notes |
|---|---|
| `limit` | Page size, 1–100. Default `30`. |
| `cursor` | The previous page's `next_cursor`. Omit for the first page. |
| `search` | Case-insensitive match on guest name / email / phone. |

**Response envelope:**

| Field | Meaning |
|---|---|
| `success` | `true`. |
| `items` | The page of results. |
| `total` | Total count. Unreliable (may be `null`) while `search` is set. |
| `next_cursor` | Opaque cursor for the next page (`null` on the last page). |
| `has_more` | Whether another page exists. |
| `usage` | Monthly allowance block — first page of a user-delegated pass listing only. |

Loop until `has_more` is `false`:

```bash
# First page
curl "https://entrybit.net/api/v1/passes?limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Next page — feed next_cursor back as cursor
curl "https://entrybit.net/api/v1/passes?limit=50&cursor=eyJpZCI6…" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Or as a lazy async generator — `api()` is the authenticated fetch wrapper from [Errors](/docs/api-reference/errors/):

```ts
type Page<T> = {
  success: true;
  items: T[];
  total: number | null;
  next_cursor: string | null;
  has_more: boolean;
};

/** Yields every pass, fetching pages only as they're consumed. */
async function* eachPass<T>(search?: string): AsyncGenerator<T> {
  let cursor: string | undefined;
  do {
    const qs = new URLSearchParams({ limit: '100' });
    if (search) qs.set('search', search);
    if (cursor) qs.set('cursor', cursor); // opaque — pass back verbatim

    const page = await api<Page<T>>(`/api/v1/passes?${qs}`);
    yield* page.items;
    cursor = page.has_more && page.next_cursor ? page.next_cursor : undefined;
  } while (cursor);
}

for await (const pass of eachPass('dana')) {
  // …
}
```

Treat `next_cursor` as **opaque** — don't parse or construct it. When `has_more` is `false`, you've read every row.

## Identifiers

Public resources use prefixed, opaque public ids — for example a pass is `gst_9f1c2ab34cd56ef7`. Use these in URLs and store them as strings; the numeric `id` some responses also include is an internal, backward-compatibility field.


## Passes

Source: https://entrybit.net/docs/api-reference/passes/

The user-delegated guest-pass API: list, create, get, and revoke passes with an OAuth access token. Request bodies, response shapes, the passes:read / passes:write scopes, and 402 on quota.

The passes API manages the **signed-in user's** guest passes. It is user-delegated: authenticate with an [OAuth access token](/docs/oauth/token/) and the `passes:*` [scopes](/docs/oauth/scopes/). All four endpoints are owner-scoped — a user only ever sees and touches passes they created.

**Base:** `https://entrybit.net` · **Auth:** `Authorization: Bearer <access_token>` · see [Conventions](/docs/api-reference/conventions/).

> The user must also still hold the organization's self-invite role. If that role is revoked, calls return `403 insufficient_scope` even with a valid token. To act across the whole organization instead, use the [Organization API](/docs/api-reference/organization/).

## The Pass object

| Field | Type | Notes |
|---|---|---|
| `public_id` | string | Public identifier, e.g. `gst_9f1c2ab34cd56ef7`. |
| `first_name` | string | |
| `last_name` | string | |
| `email` | string \| null | |
| `phone` | string \| null | |
| `status` | string | `expected`, `registered`, `checked_in`, `checked_out`, or `cancelled`. |
| `created_at` | string | |
| `arrival_date` | string | `YYYY-MM-DD`. |
| `arrival_time` | string \| null | `HH:MM`. |
| `facility_id` | integer \| null | |
| `facility_name` | string \| null | |
| `created_by` | integer | Inviting user's id — present on organization listings only. |

Status flows `expected → registered → checked_in → checked_out`, or `cancelled` if revoked.

## List passes

```http
GET /api/v1/passes?limit&cursor&search
```

**Scope:** `passes:read`. Keyset-paginated, newest first. The first page carries the monthly-allowance `usage` block.

Parameters: `limit` (1–100, default 30), `cursor`, `search` — see [pagination](/docs/api-reference/conventions/).

```bash
curl "https://entrybit.net/api/v1/passes?limit=30" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "success": true,
  "items": [ { "public_id": "gst_9f1c…", "first_name": "Dana", "status": "expected", "arrival_date": "2026-07-12", "facility_name": "North Gate" } ],
  "total": 12,
  "next_cursor": "eyJpZCI6…",
  "has_more": true,
  "usage": { "used": 8, "limit": 50, "remaining": 42 }
}
```

## Create pass(es)

```http
POST /api/v1/passes
Content-Type: application/json
```

**Scope:** `passes:write`. Creates 1–10 passes with distinct QR credentials scoped to a facility's doors, and delivers **one** email/SMS carrying a single pass link. The batch counts against the user's monthly invite allowance **all-or-nothing**.

### Request body

| Field | Required | Notes |
|---|---|---|
| `first_name` | ✓ | Max 100 chars. |
| `last_name` |  | Max 100 chars. |
| `email` | ✓* | Delivery channel — the pass email. |
| `phone` | ✓* | Delivery channel — the pass SMS. 7–15 digits. |
| `arrival_date` | ✓ | `YYYY-MM-DD` (or `YYYY-MM-DDTHH:MM`, whose time seeds `arrival_time`). |
| `arrival_time` |  | `HH:MM`; access starts here. Default: start of the arrival day. |
| `access_until` |  | Pass expiry. Default: end of the arrival day. Must not precede `arrival_date`. |
| `facility_id` | ✓ | Which facility's entry doors the QR opens. Must be active. |
| `quantity` |  | 1–10. Default `1`. One email/SMS with a single batch link. |
| `country` |  | Optional guest metadata. |
| `vehicle_number` |  | Optional guest metadata. |
| `notes` |  | Optional guest metadata. |
| `invited_by` |  | Display name shown to the guest. |

*At least one of `email` or `phone` is required so the guest can receive the pass.

```bash
curl -X POST https://entrybit.net/api/v1/passes \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Dana",
    "last_name": "Cohen",
    "email": "dana@example.com",
    "arrival_date": "2026-07-12",
    "arrival_time": "14:30",
    "facility_id": 42,
    "quantity": 1
  }'
```

### Response — `201`

| Field | Type | Notes |
|---|---|---|
| `success` | boolean | |
| `id` | integer | First guest's internal id (backward compatibility). |
| `public_id` | string | First pass's public id. |
| `qr_value` | string \| null | First pass's QR value (also in the delivered email). |
| `qr_values` | string[] | Every issued QR value, in creation order. |
| `quantity` | integer | |
| `qr_sent` | boolean | Whether the pass email was delivered. |
| `sms_sent` | boolean | Whether the pass SMS was delivered. |
| `pass_link` | string \| null | The single shareable pass page (shows all QRs in the batch). |
| `message` | string | |

```json
{
  "success": true,
  "id": 90210,
  "public_id": "gst_9f1c2ab34cd56ef7",
  "qr_values": ["EB-…"],
  "quantity": 1,
  "qr_sent": true,
  "sms_sent": false,
  "pass_link": "https://entrybit.net/p/…"
}
```

### Errors

| Status | Meaning |
|---|---|
| `400` | Validation failed — the `message`/`error` says which field. |
| `402` | Monthly invite allowance can't fit the batch (all-or-nothing). Body carries `limit`/`current`/`requested`. |
| `404` | Facility not found. |
| `409` | Facility deactivated or suspended. |

## Get one pass

```http
GET /api/v1/passes/{public_id}
```

**Scope:** `passes:read`. Owner-scoped — returns `404` for a pass the user didn't create.

```json
{ "success": true, "pass": { "public_id": "gst_9f1c…", "status": "registered", "arrival_date": "2026-07-12", "facility_name": "North Gate" } }
```

## Revoke a pass

```http
DELETE /api/v1/passes/{public_id}
```

**Scope:** `passes:write`. Cancels the pass **and** deactivates its QR credential on the door hardware. Only works while the pass is still active (`expected`/`registered`).

```json
{ "success": true, "public_id": "gst_9f1c2ab34cd56ef7", "revoked": true }
```

Returns `409` when the pass is no longer active, `404` when it isn't the user's.

## Scope summary

| Endpoint | Scope |
|---|---|
| `GET /api/v1/passes` | `passes:read` |
| `POST /api/v1/passes` | `passes:write` |
| `GET /api/v1/passes/{public_id}` | `passes:read` |
| `DELETE /api/v1/passes/{public_id}` | `passes:write` |

Full error semantics: [Errors](/docs/api-reference/errors/).


## Invitations

Source: https://entrybit.net/docs/api-reference/invitations/

GET /api/v1/invites — the pending organization invitations addressed to the signed-in user, matched by user id or email. Requires the invites:read scope.

The invitations endpoint lists the **pending organization invitations addressed to the signed-in user** — for example, an org inviting them to join as a member. It is user-delegated: authenticate with an [OAuth access token](/docs/oauth/token/) carrying the `invites:read` [scope](/docs/oauth/scopes/).

**Base:** `https://entrybit.net` · **Auth:** `Authorization: Bearer <access_token>` · see [Conventions](/docs/api-reference/conventions/).

## List invitations

```http
GET /api/v1/invites
```

**Scope:** `invites:read`. Returns invitations matched to the user by their user id or email (via a blind index), with `pending` status.

```bash
curl https://entrybit.net/api/v1/invites \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Response

```json
{
  "success": true,
  "invites": [
    {
      "id": 4210,
      "role": "member",
      "status": "pending",
      "created_at": "2026-07-08T09:15:00Z",
      "organization": "Acme Properties"
    }
  ]
}
```

### The Invite object

| Field | Type | Notes |
|---|---|---|
| `id` | integer | Invitation id. |
| `role` | string \| null | The role being offered. |
| `status` | string | Always `pending` here. |
| `created_at` | string \| null | ISO 8601 timestamp. |
| `organization` | string \| null | The inviting organization's display name. |

### Errors

| Status | `error` | Meaning |
|---|---|---|
| `401` | `invalid_token` | Missing or invalid access token — [refresh](/docs/oauth/token/) or re-login. |
| `403` | `insufficient_scope` | The token lacks `invites:read`. |

See [Errors](/docs/api-reference/errors/) for the full catalog. Accepting or declining an invitation happens in the EntryBit product UI — this endpoint is read-only.


## Organization API

Source: https://entrybit.net/docs/api-reference/organization/

The key-authenticated /api/v1/org/* API for servers and SDKs acting as the whole organization: list/create/revoke any pass, and list facilities. Scopes org:passes:* and org:facilities:read.

The organization API is the **server-to-server** data plane: endpoints for a backend or SDK acting as the **whole organization** rather than a single signed-in user. Authenticate with an [organization API key](/docs/api-keys/overview/) and `org:*` [scopes](/docs/oauth/scopes/).

**Base:** `https://entrybit.net` · **Auth:** `Authorization: Bearer eb_sk_…` (or `X-API-Key`) · see [Authenticating requests](/docs/api-keys/authenticating/).

It mirrors the [user-delegated passes API](/docs/api-reference/passes/), but organization-wide: it lists and revokes **any** pass in the company, and adds a facilities endpoint SDKs need to create passes. Everything stays tenant-scoped — a key only ever touches its own organization's data.

## List all passes

```http
GET /api/v1/org/passes?limit&cursor&search
```

**Scope:** `org:passes:read`. Every non-deleted pass in the organization, keyset-paginated newest first. Rows include `created_by` (the inviting user's id) for attribution.

Parameters: `limit` (1–100, default 30), `cursor`, `search` — see [pagination](/docs/api-reference/conventions/).

```bash
curl "https://entrybit.net/api/v1/org/passes?limit=50" \
  -H "Authorization: Bearer $ENTRYBIT_API_KEY"
```

```json
{
  "success": true,
  "items": [
    { "public_id": "gst_9f1c…", "first_name": "Dana", "status": "checked_in", "arrival_date": "2026-07-12", "facility_name": "North Gate", "created_by": 90210 }
  ],
  "total": 340,
  "next_cursor": "eyJpZCI6…",
  "has_more": true
}
```

The [Pass object](/docs/api-reference/passes/) is identical to the user-delegated API. (The `usage` allowance block is a user-delegated concept and does not appear here.)

## Create pass(es)

```http
POST /api/v1/org/passes
Content-Type: application/json
```

**Scope:** `org:passes:write`. Creates 1–10 passes with the **same request body, validation, quota, QR and delivery** as [`POST /api/v1/passes`](/docs/api-reference/passes/). Attribution and the invite quota go to the admin who minted the key.

```bash
curl -X POST https://entrybit.net/api/v1/org/passes \
  -H "Authorization: Bearer $ENTRYBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Dana",
    "email": "dana@example.com",
    "arrival_date": "2026-07-12",
    "facility_id": 42,
    "quantity": 1
  }'
```

Returns `201` with the same [`PassCreateResponse`](/docs/api-reference/passes/) shape (`public_id`, `qr_values`, `pass_link`, `qr_sent`, `sms_sent`, …). Errors: `400` validation, `402` quota, `404` facility not found, `409` facility deactivated or suspended.

## Revoke any pass

```http
DELETE /api/v1/org/passes/{public_id}
```

**Scope:** `org:passes:write`. Cancels the pass and deactivates its QR credential — **regardless of which user created it** (still scoped to the key's organization).

```json
{ "success": true, "public_id": "gst_9f1c2ab34cd56ef7", "revoked": true }
```

Returns `409` when the pass is no longer active, `404` when no such pass exists in the organization.

## List facilities

```http
GET /api/v1/org/facilities
```

**Scope:** `org:facilities:read`. The facility ids an SDK needs before it can create passes.

```bash
curl https://entrybit.net/api/v1/org/facilities \
  -H "Authorization: Bearer $ENTRYBIT_API_KEY"
```

```json
{
  "success": true,
  "facilities": [
    { "id": 42, "name": "North Gate", "description": null, "is_active": true, "suspended": false }
  ]
}
```

### The Facility object

| Field | Type | Notes |
|---|---|---|
| `id` | integer | Use as `facility_id` when creating passes. |
| `name` | string | |
| `description` | string \| null | |
| `is_active` | boolean | |
| `suspended` | boolean | Suspended facilities pause new invites. |

## Scope summary

| Endpoint | Scope |
|---|---|
| `GET /api/v1/org/passes` | `org:passes:read` |
| `POST /api/v1/org/passes` | `org:passes:write` |
| `DELETE /api/v1/org/passes/{public_id}` | `org:passes:write` |
| `GET /api/v1/org/facilities` | `org:facilities:read` |

Auth failures (`401`/`403`/`429`) follow the [API-key challenge](/docs/api-keys/authenticating/) rules; business errors follow the [error catalog](/docs/api-reference/errors/).


## Errors

Source: https://entrybit.net/docs/api-reference/errors/

The complete EntryBit error catalog: OAuth protocol codes, Bearer challenges (invalid_token / insufficient_scope), and business errors (400 / 402 / 404 / 409 / 429) — with how your app should react to each.

Every error EntryBit returns, and how to react. One rule governs all of them:

> **Branch on the `error` code, never on the human-readable text.** Descriptions are deliberately generic — they never reveal *why* a credential failed (expired vs revoked vs unknown look identical), which removes enumeration oracles. The prose can change; the codes are the contract.

## Error shapes

| Shape | Where | Body |
|---|---|---|
| **OAuth error** (RFC 6749) | [`/authorize`](/docs/oauth/authorize/), [`/token`](/docs/oauth/token/) | `{ "error": "…", "error_description": "…" }` |
| **Bearer challenge** (RFC 6750) | Any resource endpoint (`/api/v1/*`) | `{ "error": "invalid_token" \| "insufficient_scope" }` + `WWW-Authenticate` header |
| **Business error** (`AppError`) | Resource endpoints | `{ "success": false, "error": "…" }` or `{ "code": "…", "message": "…" }` |
| **Quota error** | Pass creation (`402`) | `{ "code": "CAPACITY_EXCEEDED", "dimension": "guest_invites", "limit", "current", "requested" }` |

## OAuth protocol errors

Returned by the [authorize](/docs/oauth/authorize/) and [token](/docs/oauth/token/) endpoints. On `/authorize`, protocol errors after client validation ride back on the redirect as `error`/`error_description`/`state`/`iss`; an invalid `client_id`/`redirect_uri` pair is a flat `400` (never redirected).

| `error` | Typical status | Meaning | What to do |
|---|---|---|---|
| `invalid_request` | 400 | A required parameter is missing or malformed. | Fix the request (usually `redirect_uri` or PKCE). |
| `invalid_client` | 401 | Client authentication failed. | Check `client_id` / `client_secret`. |
| `invalid_grant` | 400 | Code or refresh token expired, reused, mismatched, or family-revoked. | Clear tokens, start login again. |
| `unauthorized_client` | 400 | The client may not use this grant. | Check the client's configuration. |
| `unsupported_grant_type` | 400 | `grant_type` isn't `authorization_code` or `refresh_token`. | Use a supported grant. |
| `unsupported_response_type` | — | `response_type` isn't `code`. | Use `response_type=code`. |
| `invalid_scope` | 400 | Requested a scope the client isn't allowed. | Remove it from your scope list. |
| `access_denied` | — | The user declined consent. | Show "sign-in cancelled". |
| `login_required` | — | `prompt=none` but a login was needed. | Retry without `prompt=none`. |
| `consent_required` | — | `prompt=none` but consent was needed. | Retry without `prompt=none`. |
| `interaction_required` | — | `prompt=none` but UI was needed. | Retry without `prompt=none`. |
| `server_error` | 500 | Unexpected server error. | Retry later. |
| `temporarily_unavailable` | 429/503 | Overloaded or rate limited. | Back off and retry. |

## Bearer challenges

Returned by every resource endpoint ([Passes](/docs/api-reference/passes/), [Invitations](/docs/api-reference/invitations/), [Organization](/docs/api-reference/organization/), [UserInfo](/docs/oauth/id-token-userinfo/)) when the credential is the problem. A `WWW-Authenticate: Bearer` header carries the same code, and names the missing scope on `403`.

| Status | `error` | Meaning | What to do |
|---|---|---|---|
| `401` | `invalid_token` | Access token or API key missing, expired, revoked, malformed, or (for keys) IP-restricted — indistinguishable by design. | OAuth: [refresh](/docs/oauth/token/) then retry once; if that fails, re-login. Key: check the key/expiry/allowlist. |
| `403` | `insufficient_scope` | The credential lacks a required scope, **or** the acting user's organization role was revoked. | Don't retry as-is. Add the [scope](/docs/oauth/scopes/) (or mint a key that has it); if it's a revoked role, show "not available for your account". |

```http
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="passes:write"
```

## Business errors

Returned once the caller is authenticated but the operation can't proceed.

| Status | Code / meaning | When | What to do |
|---|---|---|---|
| `400` | Validation error | A body field is missing or invalid (create pass). | Fix the field named in `message`/`error`. |
| `402` | `CAPACITY_EXCEEDED` | The monthly guest-invite allowance can't fit the batch (all-or-nothing). | Show the quota message; the body carries `limit`/`current`/`requested`. |
| `404` | Not found | No such resource in the caller's scope (pass or facility). | Treat as absent — don't leak existence. |
| `409` | Conflict | Facility deactivated/suspended on create, or the pass is no longer active on revoke. | Show the message; the state changed underneath you. |
| `429` | `temporarily_unavailable` | Rate limit exceeded. | Back off (exponential + jitter) and retry. |

### The `402` quota body

```json
{
  "code": "CAPACITY_EXCEEDED",
  "message": "Monthly guest-invite allowance exceeded",
  "dimension": "guest_invites",
  "limit": 50,
  "current": 50,
  "requested": 3
}
```

## Reacting in code

The decision tree for any API call:

1. **`401`** → refresh the access token and retry once. Still `401`? Send the user to log in.
2. **`403`** → don't retry the same request. Fix scopes, or surface "not available for your account" if the org role was pulled.
3. **`402`** → surface the allowance message; the batch was rejected in full.
4. **`400` / `404` / `409`** → show the `message` from the body; these are request- or state-specific.
5. **`429`** → back off with jitter, then retry.

And the same tree as a fetch wrapper. `getAccessToken()` is your token layer — the [quickstart](/docs/get-started/quickstart-react-native/) has a complete implementation with single-flight refresh. (For an [API key](/docs/api-keys/authenticating/), send the key instead and drop the `401` branch — keys aren't refreshable.)

```ts
export class ApiError extends Error {
  constructor(
    readonly status: number,
    readonly code: string,  // machine-readable — branch on this
    message: string,        // human-readable — display only
    readonly body: unknown, // full payload (e.g. 402 quota details)
  ) {
    super(message);
    this.name = 'ApiError';
  }
}

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

export async function api<T>(path: string, init: RequestInit = {}): Promise<T> {
  let refreshed = false;

  for (let attempt = 1; ; attempt++) {
    const res = await fetch(`https://entrybit.net${path}`, {
      ...init,
      headers: { ...init.headers, Authorization: `Bearer ${await getAccessToken()}` },
    });
    if (res.ok) return res.json() as Promise<T>;

    // 1. 401 → refresh once, retry once. A second 401 falls through as an error.
    if (res.status === 401 && !refreshed) {
      refreshed = true;
      await getAccessToken({ forceRefresh: true });
      continue;
    }
    // 5. 429 → exponential backoff with jitter, then retry.
    if (res.status === 429 && attempt < 4) {
      await sleep(2 ** attempt * 250 + Math.random() * 250);
      continue;
    }
    // 2–4. Everything else is not retryable as-is — surface it.
    const body = (await res.json().catch(() => ({}))) as {
      code?: string; error?: string; message?: string;
    };
    throw new ApiError(
      res.status,
      body.code ?? body.error ?? String(res.status),
      body.message ?? body.error ?? `HTTP ${res.status}`,
      body,
    );
  }
}
```

At the call site, branch on `status` and `code` — never on the message text:

```ts
try {
  await api('/api/v1/passes', { method: 'POST', body: JSON.stringify(draft) });
} catch (err) {
  if (!(err instanceof ApiError)) throw err; // network error or your token layer's sign-out — rethrow
  switch (err.status) {
    case 401: return routeToSignIn();          // refresh already failed once
    case 403: return showNotAvailable();       // missing scope or role revoked — do NOT retry
    case 402: return showQuota(err.body);      // { limit, current, requested }
    default:  return showMessage(err.message); // 400 / 404 / 409 — state-specific
  }
}
```

The same philosophy runs through the [token endpoint](/docs/oauth/token/), the [React Native quickstart](/docs/get-started/quickstart-react-native/), and the [API-key challenges](/docs/api-keys/authenticating/).


## Changelog

Source: https://entrybit.net/docs/api-reference/changelog/

Dated changes to the EntryBit API — new endpoints, scopes, and behavior. Newest first.

Notable changes to the EntryBit API, newest first. Breaking changes are called out explicitly; additive changes (new endpoints, new optional fields, new scopes) are not breaking. Machine-readable history lives in the [OpenAPI spec](/docs/api-reference/openapi/).

## 2026-07 — Initial public release

The first public release of the EntryBit developer platform. Shipped:

- **OAuth 2.0 / OpenID Connect provider.** A full authorization server with the authorization-code flow and **PKCE (S256) required for every client**. Endpoints: [`/api/oauth/authorize`](/docs/oauth/authorize/), [`/api/oauth/token`](/docs/oauth/token/), [`/api/oauth/userinfo`](/docs/oauth/id-token-userinfo/), [`/api/oauth/introspect`](/docs/oauth/introspection-revocation/), [`/api/oauth/revoke`](/docs/oauth/introspection-revocation/), and RP-initiated [`/api/oauth/logout`](/docs/oauth/logout/). RS256 signing, rotating refresh tokens with reuse detection, and `iss` (RFC 9207) on all authorization responses.
- **Discovery & JWKS.** [`/.well-known/openid-configuration`](/docs/oauth/discovery-jwks/) (and the RFC 8414 alias) plus [`/.well-known/jwks.json`](/docs/oauth/discovery-jwks/) for offline token verification.
- **The `/api/v1` resource API.** User-delegated [passes](/docs/api-reference/passes/) (`list`, `create`, `get`, `revoke`) and [invitations](/docs/api-reference/invitations/), Bearer-authenticated with `passes:*` and `invites:read` scopes.
- **Organization API keys.** Server-to-server [`/api/v1/org/*`](/docs/api-reference/organization/) endpoints (org-wide passes + facilities) authenticated with `eb_sk_…` [keys](/docs/api-keys/overview/) carrying least-privilege `org:*` scopes, with optional expiry and source-IP allowlists.
- **Self-service client registration.** Org admins register their own OAuth apps in **Settings → Team → OAuth apps** ([Register an app](/docs/oauth/register-an-app/)) — public or confidential, tenant-scoped, up to 50 per org.
- **OpenID Connect identity.** `id_token` with `amr` (how the user authenticated) and `auth_time`, scope-gated identity claims, and the [UserInfo](/docs/oauth/id-token-userinfo/) endpoint.
- **Published [OpenAPI 3.1 specification](/docs/api-reference/openapi/)** and LLM-friendly [`llms.txt`](/docs/resources/tools/) resources.


## OpenAPI specification

Source: https://entrybit.net/docs/api-reference/openapi/

The entire EntryBit API as a machine-readable OpenAPI 3.1 document — where to download it, and how to use it with Swagger UI, Redoc, and client-code generators.

The entire EntryBit API — every endpoint, all three authentication models, request/response schemas, and error shapes — is published as a single **OpenAPI 3.1** document. It is the machine-readable source of truth: point tooling at it to explore the API, generate clients, or drive tests.

## Where to get it

- **Hosted:** [`https://entrybit.net/openapi.json`](https://entrybit.net/openapi.json) — always matches production.
- **In the repo:** `docs/api/openapi.json`.

```bash
curl -O https://entrybit.net/openapi.json
```

The spec is **drift-guarded** in CI: a test fails the build if an implemented public route is missing from the spec, or vice-versa — so what you download always reflects the live API.

## What's inside

| Section | Covers |
|---|---|
| `servers` | The production base URL, `https://entrybit.net`. |
| `tags` | Discovery, OAuth2, Passes, Invitations, Organization. |
| `paths` | Every endpoint documented in this reference. |
| `components.securitySchemes` | The OAuth access token, the org API key (Bearer + `X-API-Key`), and the OAuth2 flow with its scopes. |
| `components.schemas` | Concrete shapes: `TokenResponse`, `Pass`, `PassCreateRequest`, `PassPage`, `OAuthError`, `QuotaError`, and more. |

## Use it with tooling

**Interactive docs — Swagger UI or Redoc.** Render the spec as a browsable, try-it-out reference:

```bash
# Swagger UI
npx swagger-ui-watcher openapi.json

# Redoc
npx @redocly/cli preview-docs openapi.json
```

**Generate a client SDK.** Produce typed clients in your language with `openapi-generator`:

```bash
npx @openapitools/openapi-generator-cli generate \
  -i https://entrybit.net/openapi.json \
  -g typescript-fetch \
  -o ./entrybit-client
```

Swap `-g typescript-fetch` for `python`, `go`, `java`, `swift5`, `kotlin`, or any other supported generator.

**Import into a REST client.** Postman and Insomnia both import an OpenAPI document into a ready-to-run request collection — see [Postman & Insomnia](/docs/resources/postman/).

## A note on the OAuth flow

The spec models sign-in as the OAuth2 `authorizationCode` flow with PKCE. Generated clients handle the *resource* calls (`/api/v1/*`) well, but the interactive **user sign-in** is best done with a real OAuth library — `expo-auth-session` on React Native (see the [quickstart](/docs/get-started/quickstart-react-native/)), or any standard OIDC client that configures itself from [discovery](/docs/oauth/discovery-jwks/). Use the generated client for the API surface once you hold an access token.



# SDKs & tools

## Libraries & SDKs

Source: https://entrybit.net/docs/resources/libraries/

EntryBit is a standard OAuth 2.0 / OpenID Connect provider with an OpenAPI-described REST API — so you can use a well-tested OAuth library on any platform today and generate a fully-typed API client from the spec.

EntryBit is built on open standards — **OAuth 2.0**, **OpenID Connect**, and an **OpenAPI 3.1**-described REST API. There is nothing EntryBit-specific to learn: use a well-tested OAuth library for sign-in, and generate a typed client for the API from the [spec](/docs/api-reference/openapi/).

## Sign-in libraries, by platform

For "Sign in with EntryBit" (the [OAuth flow](/docs/oauth/overview/)), use the standard authorization-code + PKCE client for your platform. Point it at the [discovery document](/docs/oauth/discovery-jwks/) and it configures itself.

| Platform | Recommended library | Guide |
| --- | --- | --- |
| React Native (Expo) | `expo-auth-session` | [Quickstart](/docs/get-started/quickstart-react-native/) |
| Web (SPA / SSR) | `oidc-client-ts`, or your framework's OAuth/OIDC plugin | [OAuth overview](/docs/oauth/overview/) |
| iOS (Swift) | AppAuth-iOS | [OAuth overview](/docs/oauth/overview/) |
| Android (Kotlin) | AppAuth-Android | [OAuth overview](/docs/oauth/overview/) |
| Backend (any language) | any OAuth 2.0 client — or use an [API key](/docs/api-keys/overview/) for server-to-server | [Authentication](/docs/get-started/authentication/) |

Whatever you pick, the rules are the same: PKCE (S256) is required, tokens go in `Authorization: Bearer …`, and refresh tokens rotate — always persist the newest one.

## Generate a typed API client from OpenAPI

The [OpenAPI spec](/docs/api-reference/openapi/) at `https://entrybit.net/openapi.json` generates a fully-typed client for the REST API in any language — no hand-written request code.

| Language | Generator |
| --- | --- |
| Python | [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client) or `openapi-generator` (`-g python`) |
| TypeScript / JavaScript | [`openapi-typescript`](https://github.com/openapi-ts/openapi-typescript) (types) or `openapi-generator` (`-g typescript-fetch`) |
| Go | [`oapi-codegen`](https://github.com/oapi-codegen/oapi-codegen) |
| Swift / Kotlin / Ruby / …​ | [`openapi-generator`](https://openapi-generator.tech/) (`-g swift5` / `-g kotlin` / …) |

```bash
# TypeScript types
npx openapi-typescript https://entrybit.net/openapi.json -o entrybit.d.ts

# Python client
pip install openapi-python-client
openapi-python-client generate --url https://entrybit.net/openapi.json

# Any language, via the OpenAPI Generator
npx @openapitools/openapi-generator-cli generate \
  -i https://entrybit.net/openapi.json -g python -o ./entrybit-python
```

## Official SDKs

First-party EntryBit SDKs are on the roadmap. Until they ship, the OpenAPI spec plus the libraries above give you a typed, well-supported client on every platform — and this page will list official SDKs here as they land.

## Prefer to explore first?

Import the API straight into [Postman or Insomnia](/docs/resources/postman/) to try every endpoint interactively before you write any code.


## Postman & Insomnia

Source: https://entrybit.net/docs/resources/postman/

Import EntryBit's OpenAPI spec into Postman or Insomnia for a ready-made collection of every endpoint — with request schemas, examples, and OAuth 2.0 / API-key auth pre-wired.

The fastest way to explore the API without writing code: import the [OpenAPI spec](/docs/api-reference/openapi/) into Postman or Insomnia and you get a collection of **every endpoint**, complete with request/response schemas and examples.

## Import into Postman

1. **Import** → **Link**, and paste `https://entrybit.net/openapi.json` (or download the file and drop it in).
2. Postman builds a collection with a folder per tag and a request per endpoint.
3. Set up auth on the collection so every request inherits it (below).

## Import into Insomnia

**Create** → **Import From URL** → `https://entrybit.net/openapi.json`. Insomnia generates a request for each endpoint; set the auth on the base environment.

## Authentication in Postman

### Sign in with EntryBit (OAuth 2.0)

On the collection's **Authorization** tab, choose **OAuth 2.0** and configure:

| Field | Value |
| --- | --- |
| Grant type | Authorization Code (With PKCE) |
| Auth URL | `https://entrybit.net/api/oauth/authorize` |
| Access Token URL | `https://entrybit.net/api/oauth/token` |
| Client ID | your `client_id` (from [Register an app](/docs/oauth/register-an-app/)) |
| Code Challenge Method | SHA-256 |
| Scope | `openid profile email offline_access passes:read passes:write invites:read` |
| Callback URL | a redirect URI you registered for the client |

Click **Get New Access Token**, complete sign-in in the popup, then **Use Token**. Postman refreshes it for you.

### Organization API key

For the [organization endpoints](/docs/api-reference/organization/), choose **Bearer Token** and paste your `eb_sk_…` key. (Create one under [Manage API keys](/docs/api-keys/create-and-manage/).) Treat the collection as a secret — an API key is a server credential.

## Keep it in sync

The spec is versioned and always current at `https://entrybit.net/openapi.json` — re-import (or use Postman's "Sync" for an API) whenever you want the latest endpoints.


## LLMs & machine-readable docs

Source: https://entrybit.net/docs/resources/tools/

EntryBit publishes its docs in LLM-friendly form: llms.txt and llms-full.txt for AI assistants, plus the raw Markdown source of every page by appending .md to its URL.

EntryBit publishes its documentation in machine-readable forms so AI assistants and tooling can consume it directly and write integration code against an accurate, current picture of the platform.

Looking for code libraries or a REST client? See [Libraries & SDKs](/docs/resources/libraries/) and [Postman & Insomnia](/docs/resources/postman/). This page is about the **text** surface — for LLMs.

## For LLMs and AI tools

Following the [llms.txt convention](https://llmstxt.org/), the docs are available as clean, LLM-friendly text:

- **[`/llms.txt`](https://entrybit.net/llms.txt)** — a concise index of the documentation with links.
- **[`/llms-full.txt`](https://entrybit.net/llms-full.txt)** — the full documentation concatenated into one document, ready to paste into a model's context.

Point an AI coding assistant at these to have it work against the real API surface. Every doc page also carries a **Copy page** menu with one-click "Copy as Markdown" and "Open in ChatGPT / Claude".

## Raw Markdown for any page

Every documentation page is also available as its **raw Markdown source** — just append `.md` to the URL:

| Rendered page | Raw Markdown |
|---|---|
| `/docs/oauth/token/` | `/docs/oauth/token.md` |
| `/docs/api-reference/passes/` | `/docs/api-reference/passes.md` |

Handy for feeding a single page into a model, diffing docs, or quoting exact reference text.

## The OpenAPI spec

For a machine-readable description of the REST API itself (as opposed to the docs prose), the complete **OpenAPI 3.1** document lives at [`https://entrybit.net/openapi.json`](https://entrybit.net/openapi.json) — see [OpenAPI specification](/docs/api-reference/openapi/). It's what powers typed client generation in [Libraries & SDKs](/docs/resources/libraries/) and one-click import in [Postman & Insomnia](/docs/resources/postman/).