← Back to the Partner API overview
Integration Guide
This guide walks you through integrating the services of TeleClinic into your own application – step by step, with examples you can copy or run directly in your browser against our demo environment.
Prerequisites
All integration approaches require a federation between your identity provider (IdP) and the TeleClinic IdP via OIDC. TeleClinic requires you to provide a name, a birthdate, an email address and, if you are an insurance, the KVNR of the user who accesses our service.
Please reach out to us to set up the federation. You will receive a
subject_issuer value that identifies your organization in our systems.
Which integration fits your application?
Pick an approach to see the matching guide:
Browser-based login (Chrome Custom Tab / Safari View Controller)
If your native application already uses a Chrome Custom Tab (Android) or Safari View Controller (iOS) to log in your users, you can leverage that session to log your users into TeleClinic automatically. Use a CCT / SVC to open:
https://<DOMAIN>/oauth/<PARTNER-ID>
You will receive the values for <DOMAIN> and <PARTNER-ID>
from us during onboarding.
Our web application will redirect the user to the TeleClinic login page at
auth.teleclinic.com, which will immediately redirect the user to your
IdP. If your application uses Chrome Custom Tabs to perform the login into your own
app, the user is expected to have an active session already. They will either be redirected
back to TeleClinic immediately, or – if you configure it like this in your IdP –
get a screen where they approve their data being processed by TeleClinic.
Trade-off: depending on how your application is implemented, the user might briefly see a chain of redirects. There is no deeper integration with native functionality, like the ability to show TeleClinic information in other parts of your app. If you need that, have a look at the token exchange approach.
Token exchange
Since your user already has an active session in your application, we can leverage that session to create a session in the TeleClinic systems. By exchanging a token issued by your IdP for a token issued by the TeleClinic IdP, you can interact with the TeleClinic API directly.
Token lifetime: you will not receive a refresh token. When the access token expires, perform a new exchange.
Work through the five steps below. The shell snippets build on each other – run them in
the same shell session (they require curl and jq). Or simply press
Run in browser: the result of each step is carried over to the next one automatically.
Before interacting with TeleClinic, you must first get an access token
with a reduced scope from your own IdP. You may not use an access
token with full access to interact with any TeleClinic-owned system. The token with
the reduced scope needs to have the aud claim set to a value that is
unique to TeleClinic.
This step needs to be handled internally on your side – TeleClinic can't give any guidance for this step.
If you already have an access token from your own IdP, paste it here to continue the interactive demo with it:
or
For demonstration purposes, TeleClinic provides a dummy identity provider. Enter the credentials of the demo account to obtain an access token issued by the dummy IdP, so you can complete this guide:
Before a user can log in for the first time, an account has to be created at TeleClinic. Registering will create the account and sync information about the user in the background via OIDC. Only use this endpoint if the user agreed to have their data processed by TeleClinic.
User consent is your responsibility: this flow does not involve any TeleClinic UI for the authorization step. Before forwarding any data to TeleClinic, you must make sure that the user agreed to their data being processed by TeleClinic.
In addition to the token, you need to provide your subject_issuer value.
Each partner receives their own value during onboarding. For this demo, use
placeholder-insurance:
The endpoint responds with 201 on success, and with 400 if
an account already exists for the provided token – in that case, simply continue
with the next step.
Exchange the scoped token issued by your IdP for a token issued by TeleClinic. TeleClinic provides an endpoint which accepts your scoped access token and returns an access token issued by the TeleClinic IdP. The endpoint is documented in our OpenAPI spec.
You can now use the TeleClinic access token to interact with the TeleClinic API by
including it in the Authorization header as a Bearer token. All endpoints
are documented in our OpenAPI spec.
As an example, let's fetch the available treatment types:
To let the user continue in the TeleClinic web application without logging in again,
call POST /partner/v1/webview/open/. The endpoint returns a URL that can
be used once to open the web app in an authenticated session –
for example in a webview or a Chrome Custom Tab.
The target parameter defines which page of the web app is opened. Several
API responses (for example treatment types and treatment requests) contain
webview_target fields whose values you can pass here directly.
Open the TeleClinic web app → (the link works once, then you need to run the step again)
Environments
The examples in this guide run against our demo environment at
https://partner.be.demo.teleclinic.de. For production, use
https://partner.teleclinic.com. Your subject_issuer value and the
IdP federation are configured per environment during onboarding.
Questions?
If anything is unclear or you need support during your integration, please reach out to your TeleClinic contact person.
