> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxpressd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth

> Connect Boxpressd users with OAuth 2.0 Authorization Code flow and PKCE.

Use Boxpressd OAuth when your application needs data that belongs to a Boxpressd user. The flow uses OAuth 2.0 Authorization Code with PKCE `S256` and requires `openid`.

## Register a client

Open your application at [developers.boxpressd.com](https://developers.boxpressd.com), then open **OAuth**.

1. Choose **Public** for browser or native clients that cannot keep a secret. Public clients must use PKCE.
2. Choose **Confidential** only for a server application that can keep its client secret private.
3. Add each exact redirect URL on its own line. HTTPS is required except for localhost development.
4. Select `openid` and the scopes your application needs.
5. Click **Save OAuth settings** and copy any newly issued secret immediately.

## Supported scopes

| Scope              | Access                                                       |
| ------------------ | ------------------------------------------------------------ |
| `openid`           | Confirm the user’s identity and issue an ID token. Required. |
| `profile:read`     | Read the connected user’s profile.                           |
| `email:read`       | Include the connected user’s email address.                  |
| `humidor:read`     | Read the connected user’s humidors.                          |
| `collections:read` | Read the connected user’s collections.                       |
| `sessions:read`    | Read the connected user’s smoke sessions.                    |
| `checkins:read`    | Read the connected user’s private check-ins.                 |

## Authorize the user

Generate a high-entropy PKCE verifier, derive `BASE64URL(SHA256(verifier))`, and keep the verifier until the token exchange. Redirect the user to:

```text theme={null}
https://oauth.boxpressd.io/authorize
  ?response_type=code
  &client_id=bxp_client_...
  &redirect_uri=https%3A%2F%2Fexample.com%2Fauth%2Fcallback
  &scope=openid%20profile%3Aread%20collections%3Aread
  &state=<random-csrf-value>
  &nonce=<random-oidc-value>
  &code_challenge=<pkce-challenge>
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.boxpressd.com
```

Validate the returned `state` before exchanging the code.

## Exchange the code

```bash theme={null}
curl "https://oauth.boxpressd.io/token" \
  --request POST \
  --header "content-type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=bxp_client_..." \
  --data-urlencode "redirect_uri=https://example.com/auth/callback" \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"
```

Confidential clients also send `client_secret`. Public and native clients must not use one.

Access tokens are Bearer tokens valid for 15 minutes. Treat them as opaque. Authorization requests expire after 10 minutes, and one-time authorization codes expire after 2 minutes.

## Current limitations

* Refresh tokens are not issued. Ask the user to sign in again after expiration.
* Persistent token revocation is not implemented.
* `/userinfo` and consent-management endpoints are not implemented.
* The public Developer API is read-only. User-authorized writes are coming soon.

Discovery metadata is available at `https://oauth.boxpressd.io/.well-known/openid-configuration`.