Authentication

The user is authenticated through our SSO platform based on the standard OAuth 2.0. With the access data and the desired authorizations, the user receives a temporary key, the access token, from this platform. This token is then supplied in all requests to the OAID API for authorization purposes.

Access Credentials

client_id and client_secret identify the user to the SSO platform. You receive these once at the beginning of the contract period.

Important

The access credentials must be kept secret under all circumstances.

Even OFAA does not have access to the individual access credentials!

Transmission of the Access Credentials

For secure transmission of your access credentials, you will receive a so-called Single-use link, a service provided by Infomaniak. This link is valid for ONE week and may only be opened ONCE. Such a link may look like the following (link is shortened):

    https://kpaste.infomaniak.com/EavRvI-sAsI_kbx1.....x7iffgiyW

To prevent the link from being opened accidentally, the link is protected with a password that is additionally sent to you. After opening the link, COPY the content to a secure location, as the link cannot be reopened.

The account credentials are represented as text in TOML Format. TOML can be used by most scripting languages directly or via libraries. If not, you can simply copy the values.

Important

Save the credentials in a secure location (e.g. Password Manager).
Use established methods (e.g. Environment Variables) in your application.

Error Message

If you receive an error message when opening, either the time has expired or the link is suspected to have been opened already. In these cases, please get in touch with your contact person to create new credentials.

Access Token

To use the API, a valid access token must be included in each request. This token is - in encoded form - proof of identity and contains all the necessary information for authorization. This takes place implicitly with every API call.

Access Token

An access token is in JSON Web Token (JWT) format.
This can be parsed via standard JWT libraries or online.

An access token is valid for 300 seconds and can be used for multiple calls within that period. A new token is only needed after the previous one expires.

Tip

Reusing the access token significantly speeds up API actions.

To obtain a valid token, you need:

• client_id (corresponds to the username)
• client_secret (corresponds to the password)
• url_to_authentication_service (= the address of our identity service)
• scopes (= special permissions)

The client_id and client_secret are received once at the beginning of the contract period and are known only by you.

To locate the url_to_authentication_service, please refer to the API documentation under the OAuth2 section and use the Token URL:

Scopes are permissions that allow more precise control over access to the application. An overview of the possible scopes can be found directly in the API documentation and at each endpoint.

An interaction with the API with read-only access, for example, requires only the read permission. To generate a code, the write permission is necessary.

Recommendation

Provide an application only with the scopes it needs!

Example: Create Access Token

Below is an example for requesting an access token with the read permission (= scope).

$ curl --request POST "<token_url>" \
$   --header "Content-Type: application/x-www-form-urlencoded" \
$   --data "client_id=<your_client_id>&client_secret=<your_client_secret>&grant_type=client_credentials&scope=read"
---> 100%

{
  "access_token": "eyJhbGciOiJSU...baVQ",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "read"
}

Copy the value of the access_token from the response and insert the string at the placeholder in the HTTP Header Authorization for each request to the API:

curl --request GET --location "https://api.oaid.at/v2/pip/codes/" \
 --header "Authorization: Bearer <insert_access_token>" \      
...

Example Scripts

We provide two examples how to obtain an access token: cURL and Python.

For both examples:

• Replace <client_id> and <client_secret> with your individual credentials.
• Only provide the <scopes> that are required to perform the task.
• Use the token URL from the API documentation.

In the given examples, placeholders are indicated by angle brackets (like < ... >).

1. cURL command to be used within shell scripts

   CLIENT_ID="<client_id>"
   CLIENT_SECRET="<client_secret>"
   SCOPES="<scopes>"
   
   curl 'https://sso.yio.at/auth/realms/oaid/protocol/openid-connect/token' \
      --header 'Accept: application/json, text/plain, */*' \
      --header 'Content-Type: application/x-www-form-urlencoded' \
      --data-urlencode 'grant_type=client_credentials'  \
      --data-urlencode 'client_id='$CLIENT_ID \
      --data-urlencode 'client_secret='$CLIENT_SECRET \
      --data-urlencode 'scope='"$SCOPES"
   

2. Python (3.6+) code snippet for use within your application

   import requests
   
   client_id = "<client_id>"
   client_secret = "<client_secret>"
   scopes = "<list_of_scope_items>"
   
   url = "https://sso.yio.at/auth/realms/oaid/protocol/openid-connect/token"
   
   payload = {
       "client_id": f"{client_id}",
       "client_secret": f"{client_secret}",
       "grant_type": "client_credentials",
       "scope": " ".join(scopes)
   }
   headers = {
     'Accept': 'application/json, text/plain, */*',
     'Content-Type': 'application/x-www-form-urlencoded'
   }
   
   response = requests.request("POST", url, headers=headers, data=payload)
   
   print(response.json())
   print(response.text)