Authentication

The user is authenticated through our SSO platform based on the standard OAuth 2.0. Together 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 and used there 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 are to be kept secret under all circumstances.

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

Transmission of the Access Credentials

For the secure transmission of this data, 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

By opening the link and following the instructions, you will receive the access credentials. To prevent the link from being opened unintentionally, you must enter the password that was additionally sent. COPY the content to a secure location, you will not be able to open the link a second time.

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.
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 is required. 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

In technical terms, this is a JSON Web Token (JWT).
This can be parsed via standard JWT libraries or online.

An access token can be used for several successive calls. The validity period is 300 seconds. It is NOT necessary to generate a new token before each call. Only when the validity period expires should a new key be generated and used.

Tip

Reusing the access token significantly speeds up API actions.

To obtain a valid token, you need:

• client_id,
• client_secret and
• scopes

The client_id and client_secret are received once at the beginning of the contract period and are known only by you. The required scopes depend on the application. Scopes are comparable to authorizations that the user receives with the access token.

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 read-only permissions. To generate a code, write permissions are also required.

Recommendation

Provide an application only with the scopes it needs!

Example Access Token

Create access tokens with read permissions (= scopes) oaid:mgm:read and oaid:codes:read.

$ curl --request POST \
$   --location "https://sso.yio.at/auth/realms/oaid/protocol/openid-connect/token" \
$   --header "Content-Type: application/x-www-form-urlencoded" \
$   -d "client_id=:your client_id:&client_secret=:your client_secret:&grant_type=client_credentials&scope=oaid%3Amgm%3Aread%20oaid%3Acodes%3Aread" 
---> 100%

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

Copy the value of the access_token field from the response and insert the string at the placeholder in the HTTP Header Authorization:

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