# Authentication

To use CDQ APIs, you must properly authenticate our services.
For authentication, you can use the API key or OAuth2 Client Credentials.

## Prerequisites

1. If your organization is already a CDQ customer, ask your internal point of contact to create a CDQ dedicated account. Account detail will be sent by email.
2. If your organization is not yet a CDQ customer, please [contact us](https://www.cdq.ch/contact) to get started.


## Step 1: API Key Management

This step is common for both methods of authentication. The required type of authentication will be distinguished in the further steps.

1. Log into the CDQ [Cloud Apps](https://apps.cdq.com)


![](/assets/auth1.2efff80ac3d8732fad6294652d839f5408cdb4204fb91a00c413511987ff34b6.6fde6558.png)

1. Navigate to the "API Key Management" App


![](/assets/auth2.bee47e195c36f2c2e70e3b10558c90c732bb61a3ed617eaa94b30520b00598b7.6fde6558.png)

If no API Key Management App is visible, contact your local admin for API Key creation.

## Step 2: Generate the authentication details

1. Select the **Create a new API Key** button
2. Enter the name for the new API Key


![](/assets/auth4.cd75cd798f03dab4facc5c1b4420c85078a04c6d31787303a944309c6ea15119.6fde6558.png)

Now select authentication method: [API Key](#api-key) or [OAuth 2.0](#oauth-20)

### API Key

1. Note down the generated `API Key` is marked in the green box.


![](/assets/auth5.a22863c71f00a00146db2e0b53e003bad855e307a983b77c466110aeb9ea6889.6fde6558.png)

Check the example:


```
X-API-KEY: ZHNmd2Ratc2dzZ2RZ3NWqZHNnc2c2Rndmnc2dmZHazZ3NnZzZ3anZHM=
```

1. Click the checkbox to confirm saving the API key and close the window.


The generated `API Key` will be presented only once! The key cannot be recovered in case of loss. Consider saving `Client ID` , `Client Secret` as well.

1. Go back to a desired API section in Developer-Portal


![](/assets/auth6.696fbb7a9e45b20a51fa44239dc4c520d2477895cae9aa6da9f3f32f944ac300.6fde6558.png)

1. Copy the provided API Key and paste it to the security box in the console


![](/assets/auth7.0d4fb05fa55bc16d828c76e9976f979930ffadb949cfc149a6617cc6518ab57d.6fde6558.png)

1. Set needed parameters and try it!


### OAuth 2.0

1. Note down the generated `Client ID`and `Client Secret` are marked in the green box.


![](/assets/auth3.24f4cf4d6618496ee78c1167937286850bede4fd48aa863f542f2dcb497c7006.6fde6558.png)

Check the example:


```
Client ID: f1096473-7g01-42fa-b1c5-e747b987da61
Client Secret: 5eg123cf6sp0g
```

1. Click the checkbox to confirm saving the API key and close the window.


The generated `Client ID`and `Client Secret` will be presented only once! The credentials cannot be recovered in case of loss. Consider `saving API-KEY` as well.

1. Fetch token via token endpoint


In OAuth 2.0 approach, you must generate authentication token first.

* Use the below data in the API Client of your choice:


| Environment | Method | Token Endpoint |
|  --- | --- | --- |
| Production | POST | `https://id.cdq.com/auth/realms/cs/protocol/openid-connect/token` |


| Name | Sent as | Value |
|  --- | --- | --- |
| Content-Type | Header | application/x-www-form-urlencoded |
| Authentication | Header | "Basic " + Base64(<`Client Id`>:<`Client Secret`>) |
| grant_type | Parameter (body) | client_credentials |


Example using cURL:


```bash
curl -X POST \ https://id.cdq.com/auth/realms/cs/protocol/openid-connect/token
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d 'grant_type=client_credentials' \
     -u "<Client Id>:<Client Secret>" \
```

Example using Insomnia:

* Add a new **POST** request with the token endpoint address
* In the request body select **Form URL Encoded**
* Set `grant_type` parameter to `client_credentials`


![](/assets/oauth20-1.9d07cb4c09fe5b3c84b1fcb3344ea156d77ade11566496976c82f6da4794520a.6fde6558.png)

* Set authentication to `Basic Auth` and provide `Client ID` as a username and `Client Secret` as a password.


![](/assets/oauth20-3.8e50b1b67664dd30e373f6f18e8ec1a2e6f1fa87af6b3b89342b67dc4a301801.6fde6558.png)

* Add Header `Content-Type` with `application/x-www-form-urlencoded` value.


![](/assets/oauth20-4.2093a1cd5f9f44d345b20a6278beb569bbdb725211f8682ad345e2fee2225509.6fde6558.png)

* Hit Send


Successful response:


```
{
	"access_token": "eyJhbG...HSmgnS_0",
	"expires_in": 1800,
	"token_type": "Bearer",
}
```

Important parameters
* **access_token** - long string to be used in the API authentication
* **expires_in** - expiration time of token in seconds
* **token_type** - token type to be set in the API authentication


1. Use the authentication token
  * Select one of many CDQ's endpoints and use the below data with the new request
  * Add token to every request towards CDQ, Authentication: Bearer `<token>`


Example using cURL:


```bash
curl -X GET \ https://api.cdq.com/requiredapi
     -H "Authorization: Bearer eyJhbG...HSmgnS_0" \
```

Example using Insomnia:

* Add a new request with the required endpoint address
* Set authentication to `Bearer` and provide `access_token` value as a token.


![](/assets/oauth20-6.1e2b0e6e374a1dd6743e57dac31a6154cd54a68c60717a79555fe9da05563028.6fde6558.png)

* Hit Send


Successful response:

![](/assets/oauth20-7.e7457fa7d8e6a04c80c82be265fbac3299087d9b96975c8905d8d531655f50c6.6fde6558.png)

In the case of 403 Forbidden response check your `access_token`.

![](/assets/oauth20-8.03489c3ec3728d77fe6ca9c9ee796ac1934114d3a133b8a5cd5c58e5718cf309.6fde6558.png)

Make sure you copied the `access_token` value without **question marks**.

## Basic Authentication

CDQ doesn't recommend using Basic Authentication Header Generator for authorization anymore.

## Your opinion matters!

We are constantly working on providing an outstanding user experience with our products. Please share your opinion about this tutorial!