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.
The steps
- Send the browser to
GET /oauth/authorizewith the parameters below. - 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.
- The browser comes back to your
redirect_uriwithcode,stateandiss. Checkstateis yours andissis the issuer. - Post the code to
POST /oauth/tokenwith the PKCE verifier. - Check the access token and the ID token, then find or make your own user by
sub.
Authorize parameters
| Parameter | Required | Value |
|---|---|---|
response_type | Yes | code. Nothing else is supported |
client_id | Yes | Your client's id, cli_... |
redirect_uri | Yes | One of your registered addresses, exactly. Checked before anything else |
scope | Yes | Space separated, from openid profile email orgs offline_access, within what your client may ask for |
state | Recommended | A random value you check on return |
code_challenge | Yes | The SHA-256 of your verifier, base64url, no padding |
code_challenge_method | Yes | S256 |
nonce | No | Repeated in the ID token |
resource | No | The API the access token is for (RFC 8707). Must be in your client's resources. Without it, the token's audience is your client |
prompt | No | none 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
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.
{
"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
- A user of yours already has this
sub: that is them. - A user of yours has the same address, verified on your side, and the ID token says
email_verified: true: link them. - Neither: make a new user.
Never link by an address that is not verified on both sides.