Sign in with Beezifi

Overview

Beezifi Identity supports the OAuth 2.0 Authorization Code flow with OpenID Connect. Your application redirects users to Beezifi for authentication, receives a short-lived authorization code, and exchanges it for tokens.

• Response type: code
• Client auth: client_secret_post
• Scopes: openid profile email
• ID token signing: HS256

To get started, create a Beezifi account and register your application under My Apps.

Endpoints

Register Your Application

1. Create a Beezifi account or sign in.
2. Open My Apps from the dashboard.
3. Click Register app and fill in the app name and description.
4. Add one or more redirect URIs (one per line).
5. Save — copy your client_id and client_secret.

Redirect URI matching is strict — scheme, host, port, path, and trailing slash must all match exactly. Wildcards are not supported.

Authorization Request

Redirect your user to Beezifi to begin authentication:

GET {{BASE_URL}}/api/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/auth/callback
  &response_type=code
  &scope=openid%20profile%20email
  &state=RANDOM_CSRF_VALUE
  &nonce=RANDOM_NONCE

If the user authenticates and grants consent, they are redirected to your redirect_uri with ?code=AUTH_CODE&state=YOUR_STATE. Always verify the state value matches what you sent.

Token Exchange

Exchange the authorization code for tokens from your backend:

POST {{BASE_URL}}/api/oauth/token
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE",
  "redirect_uri": "https://yourapp.com/auth/callback",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Successful response:

{
  "access_token": "eyJ...",
  "id_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid profile email"
}

User Info

Fetch the authenticated user's profile using the access token:

GET {{BASE_URL}}/api/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Response:

{
  "sub": "user-uuid",
  "email": "user@example.com",
  "name": "Jane Doe",
  "picture": null,
  "email_verified": true
}

Error Handling

Authorization errors are returned as query parameters on the redirect URI:

• access_denied — user denied consent or an access policy blocked sign-in.
• invalid_client — bad client credentials or inactive application.
• invalid_grant — expired, already-used, or mismatched authorization code / redirect URI.
• invalid_request — missing or malformed required parameters.

Token endpoint errors are returned as JSON with an error field.

Security Checklist

• Generate a cryptographically random state value and verify it exactly on callback to prevent CSRF.
• Generate a cryptographically random nonce and validate it in the ID token.
• Store client_secret only in backend environment variables — never in client-side code.
• Use HTTPS for all redirect URIs in production.
• Validate the ID token: issuer (iss), audience (aud), expiration (exp), and nonce.
• Reject replayed or already-used authorization codes.
• Set appropriate token storage — avoid localStorage for sensitive tokens; prefer HttpOnly cookies.