Single sign-on (SAML)

​

How it works

1. Your IdP authenticates the doctor and signs a SAML assertion.
2. Your backend calls POST /v1/sso/exchange with your institution secret key and the assertion.
3. Telepatia verifies the signature, issuer, audience and validity against the SAML configuration of your institution, and returns a doctor access token plus a refresh token.
4. Your backend calls the API with the doctor token, and renews it through POST /v1/sso/refresh — no new IdP round-trip until the refresh chain ends.

​

Prerequisites

• An institution secret key (sk_…) created with the SAML SSO exchange permission (the saml:exchange checkbox in the platform’s API Keys page).
• The SAML configuration saved in the platform’s Developers → SSO tab: your IdP’s entity ID (issuer) and its signing certificate.
• The doctor must already exist in your institution. SSO authenticates doctors; it does not create them.

​

Service Provider details

​

Exchanging an assertion

curl -X POST https://scribe-api.telepatia.ai/v1/sso/exchange \
  -H "Authorization: Bearer YOUR_INSTITUTION_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "samlResponse": "PHNhbWxwOlJlc3BvbnNlIHhtbG5zOnNhbWxwPSJ1cm46..."
  }'

{
  "documentId": "acc_1234567890",
  "token": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600,
    "refreshToken": "4167f20c-d620-40c4-b0f3-8f2a1c9e7d55"
  }
}

​

Assertion requirements

• The assertion is signed (RSA-SHA256, enveloped signature) with the certificate configured for your institution.
• The Issuer equals the IdP entity ID configured for your institution.
• The Audience equals the SP entity ID above.
• The Destination equals the ACS URL above.
• The validity window (NotBefore / NotOnOrAfter) covers the moment of the exchange.
• The assertion carries an AttributeStatement — standard IdPs always include one.
• The doctor’s email arrives as the subject NameID (format emailAddress), or in the attribute named by the optional email attribute setting.

​

Refreshing the session

curl -X POST https://scribe-api.telepatia.ai/v1/sso/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "4167f20c-d620-40c4-b0f3-8f2a1c9e7d55"
  }'

​

Calling the API as the doctor

curl https://scribe-api.telepatia.ai/v1/scribe-session-configurations \
  -H "Authorization: Bearer DOCTOR_ACCESS_TOKEN"

​

Error responses

​

Example: replayed assertion

{
  "error": {
    "type": "invalid_request_error",
    "code": "permission_denied",
    "message": "SAML assertion could not be exchanged for a session."
  }
}

​

Example: invalid assertion

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "SAML assertion could not be exchanged for a session."
  }
}