UniAuth OAuth2 / OpenID Connect

Quick Start

1. Go to Account → Developer and register your app to get a client_id and client_secret
2. Redirect users to the authorization endpoint with PKCE
3. Exchange the authorization code for tokens at the token endpoint
4. Use the access token to fetch user info

Endpoints

Scopes

JavaScript Example

// 1. Generate PKCE verifier and challenge
const verifier = crypto.randomUUID() + crypto.randomUUID();
const challenge = btoa(String.fromCharCode(
  ...new Uint8Array(await crypto.subtle.digest('SHA-256',
    new TextEncoder().encode(verifier)))
)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

// 2. Redirect to authorize
const params = new URLSearchParams({
  response_type: 'code',
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://yourapp.com/callback',
  scope: 'openid profile email',
  state: crypto.randomUUID(),
  code_challenge: challenge,
  code_challenge_method: 'S256',
});
window.location.href = 'https://uniauth.id/api/oauth/authorize?' + params;

// 3. Exchange code for tokens (server-side)
const tokenRes = await fetch('https://uniauth.id/api/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: CODE_FROM_CALLBACK,
    redirect_uri: 'https://yourapp.com/callback',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    code_verifier: verifier,
  }),
});
const tokens = await tokenRes.json();

// 4. Fetch user info
const userRes = await fetch('https://uniauth.id/api/oauth/userinfo', {
  headers: { Authorization: 'Bearer ' + tokens.access_token },
});
const user = await userRes.json();

PHP Example (with SDK)

Download UniAuth.php and drop it into your project. It handles PKCE, CSRF, and token exchange automatically.

// UniAuth.php — single-file SDK, no dependencies (just PHP 8+ with curl)
require_once 'UniAuth.php';

$ua = new UniAuth(
    clientId:     'your_client_id',
    clientSecret: 'your_client_secret',
    redirectUri:  'https://yoursite.com/callback.php'
);

// ── Login page ──────────────────────────────
// Redirect the user to UniAuth:
header('Location: ' . $ua->getLoginUrl());

// ── Callback page (callback.php) ────────────
// Exchange code for user info (one line):
$user = $ua->handleCallback($_GET['code']);

// $user = [
//   'sub'            => 'uuid-of-user',
//   'email'          => 'user@example.com',
//   'email_verified' => true,
//   'name'           => 'John Doe',
//   'given_name'     => 'John',
//   'family_name'    => 'Doe',
//   'picture'        => 'https://uniauth.id/api/avatar/...',
//   '_tokens'        => ['access_token' => '...', 'refresh_token' => '...']
// ]

// Create your session, match/create user in DB, done.
$_SESSION['user'] = $user;

Python Example

import hashlib, base64, secrets, requests

# 1. Generate PKCE
verifier = secrets.token_urlsafe(32)
challenge = base64.urlsafe_b64encode(
    hashlib.sha256(verifier.encode()).digest()
).rstrip(b'=').decode()

# 2. Redirect user to:
# https://uniauth.id/api/oauth/authorize?response_type=code&client_id=...
#   &redirect_uri=...&scope=openid+profile+email
#   &state=RANDOM&code_challenge={challenge}&code_challenge_method=S256

# 3. In your callback, exchange the code:
tokens = requests.post('https://uniauth.id/api/oauth/token', data={
    'grant_type': 'authorization_code',
    'code': code_from_callback,
    'redirect_uri': 'https://yourapp.com/callback',
    'client_id': 'YOUR_CLIENT_ID',
    'client_secret': 'YOUR_CLIENT_SECRET',
    'code_verifier': verifier,
}).json()

# 4. Fetch user info:
user = requests.get('https://uniauth.id/api/oauth/userinfo',
    headers={'Authorization': f'Bearer {tokens["access_token"]}'}
).json()

Authorization Parameters

The authorization endpoint accepts several optional parameters that control the authentication experience. These follow the OpenID Connect Core specification.

Full example URL with all parameters:

https://uniauth.id/api/oauth/authorize?
  response_type=code
  &client_id=app_abc123
  &redirect_uri=https://yourapp.com/callback
  &scope=openid profile email
  &state=random-csrf-token
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &prompt=consent
  &max_age=3600
  &login_hint=jane@example.com
  &nonce=random-nonce-value

ID Token Claims

ID tokens are signed with RS256 using a rotating keypair. You can verify them using the public key from the JWKS endpoint. Below is a fully decoded example:

// Header
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "<jwk-thumbprint>"  // dynamically derived from SHA-256 JWK thumbprint
}

// Payload
{
  "sub": "2b7f16373f76cbdf9c0241ae59903ee2d143830d4edf74693b608fd2357cc219",
  "aud": "app_abc123",
  "iss": "https://uniauth.id",
  "exp": 1709903600,
  "iat": 1709900000,
  "auth_time": 1709900000,
  "amr": ["pwd", "mfa", "otp"],
  "sid": "session-identifier-hash",
  "at_hash": "access-token-hash",
  "nonce": "random-nonce-value",
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "picture": "https://uniauth.id/api/avatar/...",
  "email": "jane@example.com",
  "email_verified": true,
  "groups": ["engineering", "org:acme:admin"],  // only when the 'groups' scope is granted
  "updated_at": 1709800000
}

Claims by Scope

Client Credentials Grant

Use the client credentials grant for machine-to-machine communication where no user context is needed. This is ideal for backend services, cron jobs, or microservice-to-microservice authentication.

POST https://uniauth.id/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=openid

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "openid"
}

Token Introspection

Introspect an access token or refresh token to check whether it is currently active and retrieve its associated metadata. This is useful for resource servers that need to validate tokens without decoding the JWT themselves.

POST https://uniauth.id/api/oauth/introspect
Content-Type: application/x-www-form-urlencoded

token=eyJhbGciOiJIUzI1NiIs...
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Active Token Response

{
  "active": true,
  "sub": "2b7f16373f76cbdf9c0241ae59903ee2d143830d4edf74693b608fd2357cc219",
  "scope": "openid profile email",
  "client_id": "app_abc123",
  "token_type": "Bearer",
  "exp": 1709903600,
  "iat": 1709900000,
  "iss": "https://uniauth.id",
  "jti": "token-unique-id"
}

Inactive Token Response

{
  "active": false
}

A token is considered inactive if it has expired, been revoked, or was issued to a different client than the one making the introspection request.

End-Session / Logout

To log a user out of UniAuth and revoke their tokens, redirect them to the end-session endpoint. This follows the OpenID Connect RP-Initiated Logout specification.

GET https://uniauth.id/api/oauth/end-session?
  id_token_hint=eyJhbGciOiJSUzI1NiIs...
  &post_logout_redirect_uri=https://yourapp.com
  &state=optional-state-value

When the end-session endpoint is called, UniAuth performs the following steps:

1. Validates the id_token_hint and identifies the client and user
2. Revokes all active access tokens and refresh tokens for that client-user pair
3. Invalidates the user’s UniAuth session
4. Triggers back-channel logout notifications to other registered clients (if configured)
5. Redirects the user to the post_logout_redirect_uri with the state parameter

Back-Channel Logout

When a user logs out, UniAuth can notify all other applications the user is signed into via back-channel logout. This follows the OpenID Connect Back-Channel Logout specification.

To enable back-channel logout, configure a backchannel_logout_uri for your OAuth application in the Developer Console. When a logout event occurs, UniAuth sends a signed JWT logout token to each registered client’s back-channel URI via an HTTP POST request.

Logout Token

The logout token is a signed JWT (RS256) with the following claims:

{
  "iss": "https://uniauth.id",
  "sub": "2b7f16373f76cbdf9c0241ae59903ee2d143830d4edf74693b608fd2357cc219",
  "aud": "app_abc123",
  "iat": 1709900000,
  "jti": "unique-logout-token-id",
  "sid": "session-identifier-hash",
  "events": {
    "http://schemas.openid.net/event/backchannel-logout": {}
  }
}

Your application should verify the logout token signature using the JWKS endpoint, confirm the iss, aud, and events claims, then terminate the local session for the user identified by sub or sid. Respond with HTTP 200 to acknowledge receipt.

Pairwise Subject Identifiers

UniAuth uses pairwise subject identifiers as a core privacy feature. Each application receives a unique, deterministic identifier for each user. The same user gets a completely different sub value when signing into different applications.

This prevents cross-application user tracking — two apps cannot compare sub values to determine if the same person uses both services.

Example

The same user signing into two different applications receives different identifiers:

The pairwise sub is stable for a given user-application pair — it never changes across sessions, token refreshes, or re-authorizations. Use it as the primary key to link UniAuth users to records in your own database.

Consent Screen

When a user authorizes your application for the first time, UniAuth displays a consent screen showing the scopes your application is requesting. The user can review the permissions and choose to approve or deny access.

• First authorization: The consent screen is always shown with the requested scopes.
• Subsequent authorizations: If the user has already approved the same set of scopes, consent is auto-approved and the user is redirected immediately.
• New scopes: If your application requests additional scopes that were not previously approved, the consent screen is shown again.
• First-party applications: Applications marked as first-party in the admin dashboard bypass the consent screen entirely.
• Force re-consent: Pass prompt=consent in the authorization request to always show the consent screen, even if the user previously approved.

Common OAuth Errors

The following errors may be returned during the OAuth flow. Error responses follow RFC 6749 format with error and error_description fields.