Authentication Flow

Kotha Auth implements the standard OAuth 2.0 Authorization Code flow with PKCE (Proof Key for Code Exchange).

Each Client ID is permanently bound to one tenant by the server. The Client ID is public configuration, not a database name or a secret. Use a different Client ID for another tenant.

Step 1: Authorization

Redirect the user with your `client_id`, an exact registered `redirect_uri`, requested scope and an S256 PKCE challenge.

GET /oauth2/authorize?response_type=code&client_id=YOUR_ID&redirect_uri=YOUR_EXACT_URI&scope=openid%20profile&code_challenge=CHALLENGE&code_challenge_method=S256

Step 2: Token Exchange

After the user logs in, Kotha Auth redirects them back to your `redirect_uri` with an authorization `code`. Exchange it for an access token by verifying your `code_verifier`.

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

grant_type=authorization_code&client_id=YOUR_ID&code=THE_CODE&redirect_uri=YOUR_EXACT_URI&code_verifier=VERIFIER

Step 3: Refresh Token Rotation

Refresh tokens are one-time values. A successful refresh returns a replacement, and clients must atomically discard the predecessor.

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

grant_type=refresh_token&client_id=YOUR_ID&refresh_token=CURRENT_TOKEN

Step 4: Revoke the Session

Send the current refresh token to terminate its entire refresh-token family.

POST /oauth2/revoke
Content-Type: application/x-www-form-urlencoded

token=CURRENT_REFRESH_TOKEN&token_type_hint=refresh_token&client_id=YOUR_ID