Connect with Klang
Let users sign in with Klang and access their workspace data from your app. The flow is standard OAuth 2.0 authorization code with a confidential client, so any OAuth-compatible library works out of the box.
Overview
Connect with Klang lets a third-party application request access to a user's Klang workspace. The user signs in to Klang, approves a consent screen listing the permissions your app requests, and your app receives an access token it can use against the Klang REST API.
The flow is a confidential OAuth 2.0 authorization code grant (RFC 6749). Your app holds a client secret, so the token exchange happens server-side. PKCE is supported but not required for external clients.
$https://auth.klang.ai/.well-known/openid-configuration and $https://auth.klang.ai/.well-known/oauth-authorization-server. Register a client
A workspace admin creates an OAuth client in Settings → Developers → OAuth clients in the Klang app. The registration captures:
- Client name and logo — shown on the consent screen.
- Redirect URIs — one or more HTTPS URLs where Klang will send the authorization code.
http://localhostandhttp://127.0.0.1are allowed for local development. - Scopes — the permissions your app requests.
offline_accessis added automatically.
On creation you receive a client ID (ext_…) and a client secret (cs_…). The secret is shown once and stored hashed, so copy it immediately. If it leaks, rotate it from the same settings page.
Authorization flow
The flow has four steps: redirect the user to Klang, the user signs in and consents, your server exchanges the code for a token, then calls the API. The diagram below shows the participants and the direction of each call.
Klang - 1Redirect to /authorize
- 2Sign in + consent
- 3302 with ?code=
- 4Exchange code (server-side, with secret)
- 5access_token + refresh_token
- 6Bearer token
1. Redirect to authorize
When the user clicks "Connect with Klang" in your app, redirect their browser to the authorize endpoint with your client ID, redirect URI, requested scopes, and a random state string:
GET https://auth.klang.ai/api/auth/oauth2/authorize
?response_type=code
&client_id=ext_<your-client-id>
&redirect_uri=https://yourapp.com/oauth/callback
&scope=email%20folders:read%20conversations:read%20offline_access
&state=<random-state-string>The state parameter is your app's responsibility. Generate a cryptographically random value, store it in the user's session, and verify it matches when the redirect comes back. This prevents CSRF attacks on the callback.
PKCE is optional for external clients. If you want to use it, include code_challenge and code_challenge_method=S256 in the authorize request and send code_verifier in the token exchange.
2. User consents
Klang Auth checks whether the user has an active session. If not, it shows the email-first login page. Once signed in, the user sees a consent screen listing your app name, logo, the requested scopes, and the redirect URI. The user approves or denies access.
If the user has previously granted the same scopes to your app, Klang skips the consent screen and issues the code immediately.
3. Exchange code for token
Your redirect URI receives ?code=...&state=.... Verify the state matches, then exchange the code server-side for an access token:
POST https://auth.klang.ai/api/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(ext_<client-id>:cs_<client-secret>)
grant_type=authorization_code
&code=<authorization-code>
&redirect_uri=https://yourapp.com/oauth/callback
&resource=https://api.klang.ai/api/v1The response:
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "rt_<...>",
"id_token": "eyJhbGciOiJSUzI1NiIs...",
"scope": "email folders:read conversations:read offline_access"
} The access token is an RS256 JWT. Its claims include user_id, workspace_id, tenant_id, client_type: "klang-external", scope, and aud set to the resource URL. You can verify it against Klang Auth's JWKS endpoint if you want to validate locally.
4. Call the API
Use the access token as a bearer token against the Klang REST API:
curl https://api.klang.ai/api/v1/conversations \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." The API enforces scopes per endpoint. A token with conversations:read can list and read conversations, but not folders unless folders:read was also granted.
Scopes
The scopes your app can request are selected when registering the client. offline_access is always included automatically so the integration can refresh tokens without prompting the user again.
| Scope | Description |
|---|---|
email | Read the user's email address |
folders:read | Read folders in the connected workspace |
conversations:read | Read meetings and conversations |
offline_access | Auto-granted. Allows token refresh without re-consent |
Refreshing tokens
Access tokens expire in one hour. When the token expires, use the refresh token to get a new one without user interaction:
POST https://auth.klang.ai/api/auth/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(ext_<client-id>:cs_<client-secret>)
grant_type=refresh_token
&refresh_token=rt_<...>
&resource=https://api.klang.ai/api/v1The response has the same shape as the original token exchange. A new refresh token may be issued; replace the stored one.
Revocation
Users can revoke an app's access at any time from Settings → Profile → Connected services in the Klang app. Admins can delete the OAuth client entirely from the developer settings, which revokes all tokens issued to that client.
Once revoked, the access token is added to a revocation list in Redis and rejected on the next API call. Refresh token exchanges for that client and user also fail.
The Connect button
Klang provides official badge SVGs for the "Connect with Klang" button. Using the official badge helps users recognize the flow and trust that they are signing in to Klang, not a phishing page.