Buun Group Developers
Pages

The sign-in flow

Sign in with Buun is OAuth 2.1 with OpenID Connect: an authorization code with PKCE S256, traded at the token endpoint for an access token, an ID token and, when asked for, a refresh token.

Markdown

The steps

  1. Send the browser to GET /oauth/authorize with the parameters below.
  2. Buun Identity signs the person in at the account portal, by an emailed code and their second step when they have one. A Buun Group product's own client skips the consent page; another company's client shows it.
  3. The browser comes back to your redirect_uri with code, state and iss. Check state is yours and iss is the issuer.
  4. Post the code to POST /oauth/token with the PKCE verifier.
  5. Check the access token and the ID token, then find or make your own user by sub.

Authorize parameters

ParameterRequiredValue
response_typeYescode. Nothing else is supported
client_idYesYour client's id, cli_...
redirect_uriYesOne of your registered addresses, exactly. Checked before anything else
scopeYesSpace separated, from openid profile email orgs offline_access, within what your client may ask for
stateRecommendedA random value you check on return
code_challengeYesThe SHA-256 of your verifier, base64url, no padding
code_challenge_methodYesS256
nonceNoRepeated in the ID token
resourceNoThe API the access token is for (RFC 8707). Must be in your client's resources. Without it, the token's audience is your client
promptNonone never shows a page and answers login_required or consent_required. login and consent always show the portal

A client or redirect address that cannot be trusted gets a page at Buun Identity, never a redirect. Every other mistake goes back to your redirect_uri as error and error_description.

The token request

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


grant_type=authorization_code&client_id=cli_your_product&code=buun_ac_...&redirect_uri=https%3A%2F%2Fapp.your-product.dev%2Fauth%2Fcallback&code_verifier=...

A confidential client also proves itself, with HTTP Basic (client_secret_basic) or client_secret in the body (client_secret_post). A public client sends no secret: PKCE is its proof.

json
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "id_token": "eyJ...",
  "refresh_token": "buun_rt_...",
  "scope": "openid profile email offline_access"
}

Refreshing

grant_type=refresh_token&refresh_token=buun_rt_...&client_id=... answers new tokens and a new refresh token. The old one is spent: use it again and the whole family ends, because a refresh token used twice was stolen. A refresh token lasts 30 days.

Signing out

POST /oauth/revoke with token=buun_rt_... ends the refresh token and its family. It always answers 200 for a known client (RFC 7009).

Linking a person to your own user

  1. A user of yours already has this sub: that is them.
  2. A user of yours has the same address, verified on your side, and the ID token says email_verified: true: link them.
  3. Neither: make a new user.

Never link by an address that is not verified on both sides.