Skip to main content
With SAML single sign-on your institution holds one API key instead of one key per doctor. Your identity provider (Microsoft Entra ID, Okta, ADFS…) authenticates the doctor. Telepatia receives the signed SAML response, sends the browser back to your app with a single-use code, and your backend redeems that code for a doctor session token. Every business endpoint stays the same. Only the Authorization value changes.

How it works

  1. Your app sends the browser to GET /v1/sso/login/{institutionId} with a relayState that your app made.
  2. Telepatia sends the browser to your identity provider (IdP) with a SAML request.
  3. The doctor signs in. The IdP posts the signed SAML response to the Telepatia ACS URL of your institution, POST /v1/sso/acs/{institutionId}.
  4. Telepatia verifies the response and sends the browser (302) to the Return URL of your institution with ?code=…&state=….
  5. Your backend compares state with the value it made in step 1. Then it calls POST /v1/sso/token with your institution secret key and the code.
  6. Telepatia returns a doctor access token and a refresh token. Your backend uses them on the API and renews them with POST /v1/sso/refresh.
The SAML response never goes through your backend, and the API key never goes through the browser.

Prerequisites

  • An institution secret key (sk_…) created with the SAML SSO exchange permission (the saml:exchange checkbox in the platform’s API Keys page).
  • Access to Platform → Developers → SSO. You copy the Telepatia values from there.
  • A route in your app that receives the Return URL redirect and can call the API from your backend.
  • The doctor must already exist in your institution, with the same email that your IdP sends. SSO authenticates doctors; it does not create them.

Service Provider details

Copy these values from the Service Provider Details box in Platform → Developers → SSO. Each value has a copy button. The URLs already contain the ID of your institution. Telepatia accepts a SAML response only at the ACS URL of the institution that the response is for.

Set up your identity provider

Microsoft Entra ID

  1. In the Entra admin center, open Enterprise applications → New application → Create your own application. Select Integrate any other application you don’t find in the gallery (Non-gallery).
  2. Open Single sign-on and select SAML.
  3. In Basic SAML Configuration, set these values:
  4. In Attributes & Claims, make sure that the Unique User Identifier (Name ID) is the doctor’s email, with the format Email address. The default value is user.userprincipalname. If the UPN of your users is not their email, use user.mail.
  5. In SAML Certificates, download Certificate (Base64). Copy the App Federation Metadata Url too.
  6. In Set up your application, copy the Login URL and the Microsoft Entra Identifier.
  7. In Users and groups, assign the doctors who can sign in.
Entra can read the Telepatia values from a file. Download the file at the SP metadata URL and select Upload metadata file in the Single sign-on page.

Other identity providers

Use the same two values: the SP entity ID (audience) is the audience (Okta: Audience URI; ADFS: Relying party identifier), and the ACS URL (reply URL) is the address that receives the SAML response with the HTTP-POST binding (Okta: Single sign-on URL; ADFS: SAML Assertion Consumer endpoint). Send the doctor’s email as the NameID.

Set up the platform

In Platform → Developers → SSO, turn on Enable SAML SSO and save these values:
Import from IdP metadata URL fills the IdP fields from the App Federation Metadata Url of Entra. Examine the values and paste the certificate before you save.
After you save, the summary card shows the stored values. Examine these two rows:
  • Return URL: your address, or Not set — browser sign-in is off.
  • IdP-initiated sign-in: Allowed, or Not allowed — only sign-ins started at Telepatia.
The platform writes all the SAML values together. When you change one value, examine the Return URL and the IdP-initiated setting before you save.

Start the sign-in

Send the browser to the Sign-in URL that you copied from the platform, and add ?relayState=. In this example, INSTITUTION_ID is the ID of your institution:
  • relayState is optional, but use it. Make a new random value for each sign-in (for example, 32 random bytes in base64url), and keep it in the browser session of the user in your app. Telepatia sends it back to you as state.
  • relayState can have a maximum of 80 bytes. Do not put personal data in it.
  • The link takes no API key. Telepatia sends the browser to your IdP with a 302.
  • Too many sign-in attempts from one network get 429 with a Retry-After header.

Handle the return URL

After the doctor signs in, Telepatia sends the browser to your Return URL:
Telepatia keeps the query parameters that are already in your Return URL. It replaces a code or a state that is already there. In the route that receives this redirect:
  1. Compare state with the value that you kept in step 1. If it is missing or different, stop and show an error.
  2. Remove the state value from the session, so that it is used one time only.
  3. Send code to your backend and redeem it immediately.

IdP-initiated sign-in

A sign-in can also start in the IdP, for example from the My Apps portal of Entra. Telepatia then gets a SAML response without a SAML request.
  • When Allow IdP-initiated sign-in is off (the default), Telepatia refuses these responses with the error page saml_idp_initiated_not_allowed.
  • When it is on, Telepatia sends the browser to your Return URL with a code and without state. Your app did not start this sign-in, so it has no value to compare. Accept it only if your app permits sign-ins that start in the IdP.
To start from the My Apps tile and keep this setting off, set the Entra Sign on URL to the sign-in page of your app. Then the tile opens your app, and your app starts the sign-in with a state.

Redeem the code

Call this endpoint from your backend with your institution secret key:
Request body:
Response 200:
  • documentId is the doctor’s account.
  • expiresIn is the life of the access token, in seconds. Read it from each response. Do not use a fixed value in your code.
  • The code is valid for 90 seconds and for one use. It works only with a key of the institution that the doctor signed in to. A code that is expired, used or unknown gets 401.

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 and the Recipient equal the ACS URL of your institution.
  • When the sign-in starts at /v1/sso/login, the response carries the InResponseTo of that SAML request. A SAML request is valid for 5 minutes and for one response.
  • The validity window (NotBefore / NotOnOrAfter) covers the moment that Telepatia receives the response.
  • 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

The refresh token is the credential. No institution key and no code:
The response has the same session shape as /v1/sso/token. Refresh tokens rotate: the old one is revoked when the new pair is issued, and a second use of it returns 401.

Calling the API as the doctor

Use the access token exactly where the API key would go:

Security notes

  • Verify state. Compare it with the value that your app kept for that browser. This stops an attacker who sends a victim to your Return URL with the attacker’s code.
  • Redeem the code on your backend only. The sk_ key must never go to the browser. Do not show the code, do not log it, and do not keep it after you redeem it.
  • The code is short-lived. It is valid for 90 seconds and for one use. Redeem it as soon as your Return URL route receives it.
  • Keep IdP-initiated sign-in off unless you need it. A sign-in that your app starts carries state and an InResponseTo that Telepatia checks.
  • Keep the tokens on your backend. The access token and the refresh token give access to the doctor’s data.

Error responses

Sign-in error page

/v1/sso/login and /v1/sso/acs answer the browser, so an error is an HTML page and not JSON. The page shows a message, an error code and a request ID. It never redirects to your Return URL. Give the code and the request ID to Telepatia support.

Token errors

/v1/sso/token answers your backend with the JSON error envelope:

Example: invalid login code

Migrating from /exchange

POST /v1/sso/exchange is still supported, but it is the legacy flow. Your backend must hold the signed SAML response and send it to Telepatia. A standard IdP posts the SAML response to the browser, so this flow needs a SAML endpoint in your app. The flow on this page removes that endpoint.
  1. In the platform, set the IdP SSO URL and the Return URL. Add the Return URL route to your app (see Handle the return URL).
  2. In your IdP, add the ACS URL (reply URL) from the platform as a Reply URL and make it the default. Keep the old Reply URL (/v1/sso/exchange) until the switch is complete.
  3. Change the sign-in button of your app to send the browser to the Sign-in URL, with ?relayState=STATE.
  4. When all sign-ins use the new flow, remove the old Reply URL and the code that calls /v1/sso/exchange.
The token response, the refresh flow and the doctor token are the same in the two flows.

Legacy exchange request

The Destination of an assertion for /v1/sso/exchange is https://scribe-api.telepatia.ai/v1/sso/exchange.
The response is the same as the /v1/sso/token response. Each assertion is single use. A second exchange with the same assertion returns 403.