Token Exchange

The Token Exchange API allows you to exchange external JWT tokens for authorization codes that can be used for SSO (Single Sign-On) authentication within the platform.

Endpoint

Exchange Token for Authorization Code

Exchange a valid JWT token for an authorization code that can be used for SSO authentication.

POST /api/external/auth/token_exchange

Parameters

Example Request

curl -X POST "https://api.kismethealth.com/api/external/auth/token_exchange" \
  -H "X-Client-ID: your-client-id" \
  -H "X-Client-Secret: your-client-secret" \
  -H "Content-Type: application/json" \
  -d '{
    "token_exchange": {
      "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }'

Example Response

{
  "code": "abc123def456ghi789jkl012mno345pqr678"
}

Error Responses

401 Unauthorized - Invalid Token

{
  "error": "Invalid token"
}

401 Unauthorized - Pending Invite

{
  "error": "Please accept your invite"
}

Token Requirements

JWT Token Format

The JWT token must be:

• Properly signed with a recognized issuer’s private key
• From a registered issuer configured by the Kismet engineering team.
• Associated with a user who has accepted their organization invite
• Valid and not expired

Supported Issuers

The platform maintains a list of trusted JWT token issuers. If you wish to have us support your platform, please reach out to us. Tokens from unrecognized issuers will be rejected.

Usage Flow

1. Obtain JWT Token: Get a valid JWT token from your identity provider
2. Exchange Token: Call this endpoint to exchange the JWT token for an authorization code
3. Redirect User: Redirect your user to the Kismet Health login endpoint with the authorization code

Complete SSO Integration Example

// Step 1: Exchange your JWT token for an authorization code
const response = await fetch('https://api.kismethealth.com/api/external/auth/token_exchange', {
  method: 'POST',
  headers: {
    'X-Client-ID': 'your-client-id',
    'X-Client-Secret': 'your-client-secret',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    token_exchange: {
      token: 'your-jwt-token'
    }
  })
});
 
const data = await response.json();
const authorizationCode = data.code;
 
// Step 2: Redirect user to Kismet Health login with the code
const waitingRoomSlug = 'dr-smith-room'; // The waiting room the user should access
const loginUrl = `https://app.kismethealth.com/login?code=${authorizationCode}&redirect=/meet/${waitingRoomSlug}`;
 
// Redirect the user's browser to the login URL
window.location.href = loginUrl;

Supported Identity Providers

Each issuer must be pre-configured with:

• Issuer URL (iss claim)
• Expected audience (aud claim)
• JWKS endpoint for signature verification