# OpenAPI specification

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