Authentication

The authentication process for Platform API follows an OAuth2-compliant authentication scheme, which ensures a high level of security while allowing for easy integration. On this page, we'll cover the two main authentication methods: server to server authentication and end-user authentication.

Server to server authentication enables secure communication between a server and the API. It does this by utilizing bearer tokens, which provide a streamlined approach to authenticating every request that is sent to an API endpoint. We'll demonstrate how to obtain the necessary bearer tokens by using the client credentials grant type and provide detailed instructions on how to construct successful API requests, including all of the appropriate headers and parameters.

End-user authentication addresses scenarios where a user interaction is involved, granting the user access to specific resources based on their user permissions and consent. This section is covered in more detail in a subsequent paragraph, where we'll provide a more in depth overview of the principles that guide end-user authentication within our API ecosystem.

Server to server authentication

Platform API functionalities are securely accessible through an authentication mechanism compliant with OAuth2 (opens in a new tab).

Each request to Platform API must include a bearer token in the Authorization header.

For server to server authentication, Platform API supports the client credentials grant type.

To obtain a token that can later be used to authenticate all subsequent API requests, you’ll need to issue an API call with the following request details:

• URL: https://api.infermedica.com/api/auth/token - Platform API is accessible via the same domain as other APIs provided by Infermedica.
• Instance-Id - header, specific to each Platform API instance. You will receive this value during the provisioning process of your API instance. Required only for API actions related to authentication. After a bearer token is obtained, this data is encoded in the token itself.
• Authorization - header, conforms to the HTTP Basic Authentication scheme described in RFC 7617 (opens in a new tab) and should therefore be a base64 encoded concatenation of the client's credentials: Basic Base64Encode(app_id:app_key). Both Application Id and Application Key are provided by Infermedica.
• scope - attribute (optional), useful for defining the set of API actions available after receiving an access token. Actions not listed in scope will not be accessible in the context of the current session. If not provided, scope will default to all of the OAuth2 scopes available for the given Application Id. List of all available scopes.

Such a request may look like this:

Example:

curl "https://api.infermedica.com/api/auth/token" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -H "Instance-Id: <INSTANCE_ID>-mgp" \
  -H "Authorization: Basic <CREDENTIALS>" \
  -d '{
    "grant_type": "client_credentials",
    "scope": "user:read user:write patient:read patient:write survey:read"
  }'

In response, you will obtain a JWT (opens in a new tab) access token, the token type, and an expiration time for the token. The default value for expiration time is 3600 seconds (1 hour).

Example:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBfaWQiOiJhYTExYmIyMiIsImV4cCI6MTcxNDQ4NTUyMSwiaWF0IjoxNzE0NDgxOTIxLCJpbnN0YW5jZV9pZCI6IjxJTlNUQU5DRV9JRD4tbWdwIiwiaXNzIjoiYXBpLWdhdGV3YXkiLCJzY29wZSI6InVzZXI6d3JpdGUgcGF0aWVudDpyZWFkIHBhdGllbnQ6d3JpdGUgc3VydmV5OnJlYWQifQo.nXJr2JIgwisi4-tuUgzVyVTyymPI4JbXSLqqKRB5mDJHOgQaYLOx7aTNq-ZteoxUzuFxBcud7chk5yiGatafsBYIKRZmcmFZUgtQXdP4K7pEZUD9nbtqDGgP2x5dkme3fcRzO2Bo07is9cBQRdmju9ns-hWgn8ieUJq64rwh13eJC6OTd2qvxNmxFkwVLi8SrCxp0CRxwV9DHQCbY1DvXkS45c7FcHghvtuBTyO-Y0FAzmZQoHEmwesrigXnvNeapiHiurslJ0dSyEfmv01Yin0mL2Skt8kCUPSDfQYxbVf-PH8w0-_sF4LiShEzdliNFyufZrL_NQwXEdsCASxTTw",
  "token_type": "Bearer",
  "expires_in": 3600
}

The expires_in field specifies the lifetime of the access token in seconds. After this time, the token will expire and a new token must be obtained.

This access_token can then be used to authenticate other requests to the API. For example, to fetch all users use:

curl "https://api.infermedica.com/api/mgp/v1/users" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

OAuth2 scopes overview

Here is a list of all of the OAuth2 scopes available in Platform API:

End-user authentication

End-user authentication is essential in scenarios where the API client needs to perform API actions on behalf of individual users, such as when integrating a mobile app or a front-end application. There are two possible methods available to authenticate an end-user: one-time password(otp) and magic link(magic_link).

One-time password flow

The client application needs to call the /api/mgp/v1/auth/otp endpoint with either the user's email (using the attribute email) or phone number (via phone) in the body (but not both at the same time) in order to obtain a one-time password:

curl "https://api.infermedica.com/api/mgp/v1/auth/otp" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -H "Instance-Id: <INSTANCE_ID>-mgp" \
  -d '{"email": "user@example.net"}'

A successful response will have an HTTP status code of 204 and will have no body. It will trigger an email or SMS/text message with a one-time password that’s sent to the end-user.

The client application can then use the /api/mgp/v1/auth/login/otp endpoint to log the user in by passing the otp and receiving an access token:

curl "https://api.infermedica.com/api/mgp/v1/auth/login/otp" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -H "Instance-Id: <INSTANCE_ID>-mgp" \
  -d '{
    "email": "user@example.net",
    "otp": "123456"
  }'

Response:

{
  "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2NvZ25pdG8taWRwLmV1LWNlbnRyYWwtMS5hbWF6b25hd3MuY29tL2V1LWNlbnRyYWwtMV9VQkZmUTNmR28iLCJleHAiOjE3MTU3MDA0MjUsInVpZCI6ImZiYWU1YjAwLTBhOTgtNGUxOS05YWM0LWRlZGI1YTIyMjc4NSIsImF1ZCI6IjJta283bWUxYzBxdHF2czhtM3RkdmY5MnYxIiwiaW5zdGFuY2VfaWQiOiI8SU5TVEFOQ0VfSUQ+LW1ncCIsImFwcF9pZCI6bnVsbCwic2NvcGUiOiJrbm93bGVkZ2U6cmVhZCBwYXRpZW50OnJlYWQgcXVlc3Rpb246cmVhZCBxdWVzdGlvbjp3cml0ZSBzdXJ2ZXk6cmVhZCIsInVuYW1lIjoiZmJhZTViMDAtMGE5OC00ZTE5LTlhYzQtZGVkYjVhMjIyNzg1In0K.Kk62KIcbaFlAYYMLpBhMIZsBSKMn2cdHesOQQHil7uk_f6569ZXP1gyTVlOKEzlnSk33TguZze_A4c3MXcS0zJD1P_WmLkfdUWLweiX4us6RWk1ywSwhP67yH2ERLFr7PBNS0PoByhAMnUZ7paXbNL58xmvo_1ItcvJkF-2oaT8vOVmgVxmnqkEGC_2Lc3qsUMt_d24DMF3P21qdt_BzCYmwlHCh6l_4QBVu1hEGqXXRQrmPuThfrpfN2C6lACoXe3lwJ49udAgsfOAn0I9q-amFqMYi3ByqWFIno_lAVPS4bp2T-1fU6Fet6oM5IsIBZcjUjC8HZiMkQ301alkZzYHfMOEhNSBs1-7ALHnqTXZIPqtoxgUdSUAUIOYMK0xwX1ubbO9IvSgZvsPpg1_Cc3eflOB3sv51LoJSxOTvUoWjw-R9ds4KIS2DpvTqEiTLV0uP1FvE0ShMEvMdaoVFM_59Uup3QBJESSQIDI_w4IUJPYSbAY1FYoSAq5dAEecKmgg_NwJcj2RnfUVAD-70HTmVfdeOIrlBVFg7tlVGs2pE6zTMX3lTZbdRBiCMuNY5VyQQ9wcIg1F8-gsyoD9JQTC-1esZysVU70nKqsh_5wEeOZy_3t4ScmLcokH5e-K8DqygpggAX1Q1_xiOcn6Lh9hvKyjIBYQXH14HsUtZRvE"
}

Magic link flow

The client application needs to call the /api/mgp/v1/surveys/{survey_id}/magic_link endpoint. This endpoint is secured with a bearer token, as described in the server to server authentication section. In order to use the magic link flow, you first have to create a survey and provide that survey's identifier in the API call, as such:

curl "https://api.infermedica.com/api/mgp/v1/surveys/{survey_id}/magic_link" \
  -X "GET" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Response:

{
  "magic_link": "https://<INSTANCE_ID>-mgp.infermedica.com/en/33effe11-75dc-4a84-833f-1795b187cc9b?magicCode=e4UFEmimt"
}

The client application can then use the /api/mgp/v1/auth/login/magic_code endpoint to log the user in by passing the magic code and receiving an access token:

curl "https://api.infermedica.com/api/mgp/v1/auth/login/magic_code" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -d '{
    "code": "e4UFEmimt",
    "resource_type": "survey",
    "resource_id": "33effe11-75dc-4a84-833f-1795b187cc9b"
  }'

Response:

{
  "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2NvZ25pdG8taWRwLmV1LWNlbnRyYWwtMS5hbWF6b25hd3MuY29tL2V1LWNlbnRyYWwtMV9zN0k5YUJtV1EiLCJleHAiOjE3MTU3MTg3MTMsInVpZCI6IjFjNTBiYmMwLTM0N2YtNGYwZC04N2Q1LWRjY2U5MGEyOGIzMCIsImF1ZCI6IjJoYjhtNjQzY2M0aHA0cTc1azIzdGp1dWdpIiwiaW5zdGFuY2VfaWQiOiI8SU5TVEFOQ0VfSUQ+LW1ncCIsImFwcF9pZCI6ImU2NTZmYWYzIiwic2NvcGUiOiJrbm93bGVkZ2U6cmVhZCBwYXRpZW50OnJlYWQgcXVlc3Rpb246cmVhZCBxdWVzdGlvbjp3cml0ZSBzdXJ2ZXk6cmVhZCIsInVuYW1lIjoiMWM1MGJiYzAtMzQ3Zi00ZjBkLTg3ZDUtZGNjZTkwYTI4YjMwIn0K.qpqQYFo36UpcM6dxk9RqVaVDLaXLvLrrkf_91ecc3nQPScM1isyKGYsPKCb_r3wq56R5mWCD8ihia-QOggTuwdFPNI5TNCwVvDjFcMxKrPbfvr_dk-qBLJhwBbFbemnQtvi9nSSL2am5ntf1IvvFkb9Lckcj8St3kZOcjUjG5HAWxDQIL9ODjgaeyHzNF-6-zKTNsCSvtY0HHx4I_x-vRIMfqCyQzPkoieX4gYFaDPJ_3w2nj1DU34OJlRAqRORDGLRtym3DYJEBKQafR_MaA-MlLvndX4NYUmOSPdJ0LkeB11GKCXzMqo-EptFl9PDdlAnZL5z0_K0AsJFKm3HAdZohOEsxTzeJIYZnDqaDxDiXrG-x4NVYtPnQt7EHvFWnRXF1eXbyIdDg3Y7dICUHIDHoV4bQuv8cCY1-euiyW-vwVhtbF_euoSVQu3y42OHFy5Vj2MGm3fbj6apGYTkiw3Uukx-o150swzix26R40_TyDsryzR-6d3_aShjBBHNoTYDuPDNc8rezTiiNC7FC8ZL5O_s-BRxoqFEjR_Rg_T80T_SzST48uGHhL8YIzwDElIuCOD4w1TnEgcJ9YfBjooo1OwZp44Clux_MnjWEn5kXPsLbn8MClvYCV-QNjeHWEiY-IKlqvAhPlyWV60z_TpkDIH-ZmIVjXfzMZ63WxSc"
}