# 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.