Authorization value changes.
How it works
- Your app sends the browser to
GET /v1/sso/login/{institutionId}with arelayStatethat your app made. - Telepatia sends the browser to your identity provider (IdP) with a SAML request.
- The doctor signs in. The IdP posts the signed SAML response to the Telepatia ACS URL of your institution,
POST /v1/sso/acs/{institutionId}. - Telepatia verifies the response and sends the browser (
302) to the Return URL of your institution with?code=…&state=…. - Your backend compares
statewith the value it made in step 1. Then it callsPOST /v1/sso/tokenwith your institution secret key and thecode. - 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.
Prerequisites
- An institution secret key (
sk_…) created with the SAML SSO exchange permission (thesaml:exchangecheckbox 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
- 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).
- Open Single sign-on and select SAML.
-
In Basic SAML Configuration, set these values:
-
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, useuser.mail. - In SAML Certificates, download Certificate (Base64). Copy the App Federation Metadata Url too.
- In Set up your application, copy the Login URL and the Microsoft Entra Identifier.
- In Users and groups, assign the doctors who can sign in.
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 theNameID.
Set up the platform
In Platform → Developers → SSO, turn on Enable SAML SSO and save these values:
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.
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:
relayStateis 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 asstate.relayStatecan 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
429with aRetry-Afterheader.
Handle the return URL
After the doctor signs in, Telepatia sends the browser to your Return URL:code or a state that is already there.
In the route that receives this redirect:
- Compare
statewith the value that you kept in step 1. If it is missing or different, stop and show an error. - Remove the
statevalue from the session, so that it is used one time only. - Send
codeto 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
codeand withoutstate. 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.
state.
Redeem the code
Call this endpoint from your backend with your institution secret key:200:
documentIdis the doctor’s account.expiresInis 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
Issuerequals the IdP entity ID configured for your institution. - The
Audienceequals the SP entity ID above. - The
Destinationand theRecipientequal the ACS URL of your institution. - When the sign-in starts at
/v1/sso/login, the response carries theInResponseToof 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(formatemailAddress), 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:/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
stateand anInResponseTothat 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.
- 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).
- 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. - Change the sign-in button of your app to send the browser to the Sign-in URL, with
?relayState=STATE. - When all sign-ins use the new flow, remove the old Reply URL and the code that calls
/v1/sso/exchange.
Legacy exchange request
TheDestination of an assertion for /v1/sso/exchange is https://scribe-api.telepatia.ai/v1/sso/exchange.
/v1/sso/token response. Each assertion is single use. A second exchange with the same assertion returns 403.