Authentication and Authorization

Table of contents

1. Obtaining your API Credentials
2. OAuth Roles
3. Authorization
4. Access Tokens
5. Access to Protected Resources

The samedi API utilizes the OAuth 2.0 standard to allow allows external services and applications to authenticate themselves. This documentation assumes a basic familiarity with the OAuth 2.0 framework and protocol.

If you are new to OAuth you may want to have a look at the basic concepts of OAuth or the actual OAuth 2.0 specification (RFC6749).

Obtaining your API Credentials

To use the samedi API you need to have a unique Client Key and a Client Secret. You can obtain these without any cost by signing up in this registration form. You will receive your credentials immediately through an e-mail.

You can use these credentials along with any OAuth library of your choice to sign any requests you send to the samedi API. This allows samedi to ensure that the requests are trustworthy and that they originate from legitimate services or applications. API methods that require such signing are explicitly marked as such in the following documentation.

In addition to the OAuth signing process, simpler operations require only an API key passed as a URL parameter along with your GET request. Your API Key is the same as your Client Key. Methods that require the API key are marked explicitly in the following documentation.

OAuth Roles

OAuth 2.0 specifies 4 distinct roles. In the context of samedi these are mapped as following:

• The Resource Owner is the samedi user on whose behalf appointments are booked.
• Your external application or service acts as the Client and can access Resource Owner’s data, but only with their prior permission.
• The samedi API serves as an interface to the Resource Servers which control access to protected resources by means of tokens.
• Furthermore, the API interfaces to the Authorization Server which after successful authorization provides the appropriate Resource Owner Access Tokens.

The interaction sequence between these roles is the following:

1. The Client requests the authorization of the Resource Owner (samedi user). The latter may grant her authorization by logging in to her samedi account.
2. The Client then receives the User Authorization from samedi’s Authorization Server.
3. The Client then presents its Client Key, Client Secret and the User Authorization to samedi’s Resource Server (via the API).
4. Upon validation, samedi’s Resource Server returns to the Client an Access Token.
5. The Client requests access to the protected resources and signs these requests with the Access Token
6. samedi, upon successful validates of the Access Token, returns the requested resource.

Authorization

The endpoint https://patient.samedi.de/api/auth/v2/authorize is used to obtain authorization from the Resource Owner. This authorization is represented in the form of an Authorization code which can be subsequently used to request an Access Token. Since some of our APIs are protected by certain oauth scope, depending on the use cases, you might also want to specify corresponding scopes in the request.

Please note: If no scope is provided, all rights will be added to the authorization request. These are, currently: ‘appointments:read’, ‘appointments:book’ and ‘profile:read’.

The exact authorization steps are as follows:

• The Client redirects the Resource Owner in the authorization endpoint while setting its Client Key, its Redirect URI and scope. This is a callback URL to which the Resource Owner will be redirected upon approving (or rejecting) the authorization request.
• The samedi Authorization Server authenticates the Resource Owner by means of samedi patient login credentials (a username and a password).
• Upon Resource Owner’s successful login, the latter is forwarded to the Client’s Redirect URI with the addition of an Autorization Code and the allowed scope.

A sample GET request for authorization might look like this:

GET /api/auth/v2/authorize?response_type=code&client_id=CLIENT_ID&redirect_uri=https://client.example.com/cb&scope=appointments%3Abook%20profile%3Aread
HTTP/1.1
Host: patient.samedi.de

The server’s response upon successful authorization, including the Authorization Code, is of the following format:

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=AUTHORIZATION_CODE&scope=appointments%3Abook+profile%3Aread

If the Resource Owner declines authorization the response will instead look like:

HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=access_denied&error_description=The+user+denied+you+access

There are more error possibilities implemented by the samedi API according to the official specification.

The authorization endpoint can accept custom state parameters, which make sense in the context of your application, which will be returned back unchanged as parameters in the Client’s Redirect URI.

Access Tokens

After successful authorization the Client can use the https://patient.samedi.de/api/auth/v2/token endpoint to request an Access Token. In more detail:

• The Client requests from the samedi API an Access Token by providing these body form params: Client Key, Client Secret, and the previously obtained Authorization Code. A Redirect URI (callback URL) should also be provided in the same request.
• Upon successful validation an Access Token, together with its scope (if any), is returned.

A sample POST request for an Access Token might look like this:

POST /api/auth/v2/token HTTP/1.1
Host: patient.samedi.de
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&code=AUTHORIZATION_CODE
&redirect_uri=https://client.example.com/cb

A validated and successful response will include an access token:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
"access_token":"ACCESS_TOKEN",
"scope":"profile:read appointments:book"
}

For any malformed or otherwise incorrect request the samedi API will respond with an HTTP status code of 400:

HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store

{
"error":"invalid_request"
}

The included error descriptions are following the OAuth 2.0 Specification.

Access to Protected Resources

Once the Client has a valid access token with required scope, it can access the protected resources on behalf of the Resource Owner. For example, for a GET request to the https://patient.samedi.de/api/booking/v3/user endpoint, the Authorization HTTP header should be used as following:

GET /api/booking/v3/user HTTP/1.1
Host: patient.samedi.de
Authorization: Bearer ACCESS_TOKEN

Upon successful authorization, the protected resource is returned. For example:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "user": {
    "id": "e3cbc797-59f0-4d36-b54b-f63ccd0d555e",
    "email": "auto-fahrer@samedi.de",
    "full_name": "Auto Fahrer",
    "first_name": "Auto",
    "last_name": "Fahrer",
    "insurance_number": "",
    "insurance_company_id": "280",
    "gender": "",
    "title": "",
    "phone": "",
    "mobile": null,
    "born_on": "1960-01-01",
    "street": "Teststr. 1",
    "zip": "10115",
    "city": "Berlin"
  }
}

If the access token is invalid or missing the API will respond with an HTTP status code of 401 - Unauthorized.