Authentication¶
Every Sahl AI integration starts with an access token. The token identifies your organization and the clinician using Sahl AI. It authorizes the embedded panel and the streaming API.
There are two ways to get a token:
-
Username and password
Your backend calls
POST /users/loginwith integration credentials issued by Sahl AI, and names the signed-in clinician. -
Signed JWT (PKI)
Your HIS signs a short-lived assertion with its own RSA private key. Sahl AI verifies it with the public key you registered and issues a session token.
Comparison¶
| Username and password | Signed JWT (PKI) | |
|---|---|---|
| Secret held by you | Integration username and password | RSA private key (never shared) |
| Secret held by Sahl AI | Credentials | Your public key only |
| Token lifetime | expires_in seconds (24 hours by default), renewable with a refresh token |
2 hours, not renewable. Sign a new assertion instead. |
| Clinician identity | identifier field on login |
email claim in the assertion |
| Setup | Credentials issued by Sahl AI | Key registration with Sahl AI (see Onboarding) |
Using the token¶
| Where | How |
|---|---|
| Embedded panel, secure handshake | access_token in the SAHL_IFRAME_INIT payload |
| Embedded panel, URL mode | access_token query parameter |
| Embedded panel, JWT mode | Send the signed JWT itself as token. The panel exchanges it for you. |
| Streaming API | Second WebSocket subprotocol: ["listen-protocol", token] |
Security requirements¶
- Request tokens from your backend. Do not embed credentials or private keys in front-end code.
- Send tokens over TLS only. Do not write them to logs, analytics or error reports.
- Request a fresh token for each clinician session. Do not share one token across clinicians.
- Tell Sahl AI straight away if credentials or keys may have been exposed, so they can be rotated.