Authorization URL

Build an OAuth 2.1 authorization URL with PKCE (Proof Key for Code Exchange). PKCE is mandatory for all authorization code flows per OAuth 2.1.

buildAuthorizationUrl()

Generate the authorization URL and PKCE code verifier. Redirect the user's browser to this URL to begin the OAuth flow.

client.oauth.buildAuthorizationUrl(params: AuthorizationUrlParams): AuthorizationUrlResult

Parameters

Name	Type	Required	Description
`scopes`	`string[]`	yes	OAuth scopes to request
`redirectUri`	`string`	yes	URI to redirect to after authorization
`state`	`string`	no	Opaque value for CSRF protection (auto-generated if omitted)
`nonce`	`string`	no	OIDC nonce for ID token replay protection
`prompt`	`"none" \| "login" \| "consent" \| "select_account"`	no	OAuth prompt behavior
`loginHint`	`string`	no	Pre-fill the email field on the login page
`organizationId`	`string`	no	Restrict to a specific organization
`acrValues`	`string`	no	Authentication context class reference

Returns

interface AuthorizationUrlResult {
  url: string;            // Full authorization URL to redirect to
  codeVerifier: string;   // PKCE code verifier (store securely for code exchange)
  state: string;          // State parameter (auto-generated if not provided)
}

Basic usage

import { AvnologyId } from "@avnology/sdk-typescript";

const client = new AvnologyId({
  baseUrl: "https://api.id.avnology.com",
  clientId: "app_abc123",
});

const { url, codeVerifier, state } = client.oauth.buildAuthorizationUrl({
  scopes: ["openid", "profile", "email"],
  redirectUri: "https://myapp.com/callback",
});

// Store codeVerifier and state in session storage for the callback
sessionStorage.setItem("pkce_code_verifier", codeVerifier);
sessionStorage.setItem("oauth_state", state);

// Redirect to the authorization URL
window.location.href = url;

Available scopes

Scope	Description
`openid`	Required for OIDC. Returns an ID token.
`profile`	User's name, locale, timezone
`email`	User's email and verification status
`phone`	User's phone number
`offline_access`	Returns a refresh token
`organizations`	Organization membership info
`permissions`	Permission/role claims
`users:read`	Read user data (admin)
`users:write`	Write user data (admin)
`organizations:read`	Read org data (admin)
`organizations:write`	Write org data (admin)

With all options

const { url, codeVerifier, state } = client.oauth.buildAuthorizationUrl({
  scopes: ["openid", "profile", "email", "offline_access", "organizations"],
  redirectUri: "https://myapp.com/callback",
  state: crypto.randomUUID(),       // Custom state for CSRF
  nonce: crypto.randomUUID(),       // Nonce for ID token validation
  prompt: "consent",                // Always show consent screen
  loginHint: "[email protected]",    // Pre-fill email
  organizationId: "org_abc123",     // Restrict to org
});

Organization-scoped authorization

When organizationId is provided, only members of that organization can authorize. This is useful for B2B SaaS apps that require users to belong to a specific tenant.

const { url, codeVerifier } = client.oauth.buildAuthorizationUrl({
  scopes: ["openid", "profile", "email", "organizations"],
  redirectUri: "https://myapp.com/callback",
  organizationId: "org_abc123",
  prompt: "login",  // Force re-authentication
});

Silent authentication (check existing session)

Use prompt: "none" to check if the user has an existing session without showing any UI. Useful for SPAs that want to silently restore a session on page load.

const { url, codeVerifier } = client.oauth.buildAuthorizationUrl({
  scopes: ["openid", "profile", "email"],
  redirectUri: "https://myapp.com/silent-callback",
  prompt: "none",
});

// Redirect in a hidden iframe
const iframe = document.createElement("iframe");
iframe.style.display = "none";
iframe.src = url;
document.body.appendChild(iframe);

// Listen for the callback message
window.addEventListener("message", (event) => {
  if (event.origin === "https://myapp.com") {
    const { code, error } = event.data;
    if (code) {
      // Exchange code for tokens
      exchangeCode(code, codeVerifier);
    } else {
      // No session -- show login button
      showLoginButton();
    }
  }
});

Generated URL structure

The generated URL follows the OAuth 2.1 specification:

https://api.id.avnology.com/oauth2/auth
  ?response_type=code
  &client_id=app_abc123
  &redirect_uri=https%3A%2F%2Fmyapp.com%2Fcallback
  &scope=openid+profile+email
  &state=abc123
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

Authorization URL

Authorization URL

buildAuthorizationUrl()

Parameters

Returns

Basic usage

Available scopes

With all options

Organization-scoped authorization

Silent authentication (check existing session)

Generated URL structure

See also

On this page