API GUIDE

IDP Integration

The Kleis Auth Server can be used completely independently of any SDK. It implements standard OIDC specifications, allowing integration via any HTTP client or OIDC library.

Endpoints

Kleis exposes standard OIDC endpoints for discovery and authentication:

Discovery

/.well-known/openid-configuration

Authorization

/authorize

Token

/token

UserInfo

/userinfo

JWKS

/.well-known/jwks.json

Logout

/auth/logout

PKCE Flow

1. Authorization Request

Redirect the user to the /authorize endpoint with your PKCE code_challenge.

HTTP GET

GET /authorize?
  client_id=your_client_id&
  redirect_uri=https://yourapp.com/callback&
  response_type=code&
  scope=openid profile email&
  state=random_state_string&
  code_challenge=base64_encoded_challenge&
  code_challenge_method=S256

2. Handle the Callback

After the user authenticates, the IdP will redirect back to your redirect_uri with code and state parameters.

Example Callback

GET https://yourapp.com/callback?code=auth_code_123&state=random_state_string

Security Check: Verify that the state matches the one you originally sent.

3. Exchange Code

Exchange the authorization code for tokens using yourcode_verifier.

HTTP POST /token

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

grant_type=authorization_code&
code=auth_code_received&
redirect_uri=https://yourapp.com/callback&
client_id=your_client_id&
client_secret=your_client_secret&
code_verifier=original_unhashed_verifier

Response

{
  "access_token": "...",
  "id_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 900
}

User Info

Fetching Profile Data

Use the access_tokento access the user's profile from the /userinfo endpoint.

HTTP GET /userinfo

GET /userinfo
Authorization: Bearer <access_token>

Response

{
  "sub": "user_id_123",
  "email": "user@example.com",
  "given_name": "John",
  "family_name": "Doe",
  "picture": "https://..."
}

Refreshing Tokens

Obtain a new access token

When an access_token expires, use the refresh_token to obtain a new one.

HTTP POST /token

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

grant_type=refresh_token&
refresh_token=your_current_refresh_token&
client_id=your_client_id&
client_secret=your_client_secret

Logging Out

End the user session

To end the user's session on the IdP, redirect them to the /auth/logout endpoint.

HTTP GET /auth/logout

GET /auth/logout?client_id=your_client_id&post_logout_redirect_uri=https://yourapp.com/

Pro Tip: Standard Compatibility

Because Kleis follows the OpenID Connect specification, you can use popular libraries like openid-client (Node.js),AppAuth (iOS/Android), orgolang.org/x/oauth2 without any Kleis-specific code.