OAuth

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, then open OAuth.

Choose Public for browser or native clients that cannot keep a secret. Public clients must use PKCE.
Choose Confidential only for a server application that can keep its client secret private.
Add each exact redirect URL on its own line. HTTPS is required except for localhost development.
Select openid and the scopes your application needs.
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:

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

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.

Getting started

API guides

REST reference

Register a client

Supported scopes

Authorize the user

Exchange the code

Current limitations

​Register a client

​Supported scopes

​Authorize the user

​Exchange the code

​Current limitations

Register a client

Supported scopes

Authorize the user

Exchange the code

Current limitations