# Authentication

### Getting your API secret key

The Dastra REST API uses API keys to authenticate each request. You can manage your keys in the [API configuration section of your organization](https://app.dastra.eu/general-settings/api).

You can use an API key for a specific workspace or for the entire organization.

Your API key allows you to perform many actions, so you must keep it safe. Do not share your secret key in public parts of applications such as GitHub, client-side code, etc.

If you want to use OAuth2 authentication with the "authorization\_code" flow, you must configure the redirect URLs and allowed CORS origins properly.

![](https://1301193153-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LvBxs22wUMicv9uWp6C-2584506019%2Fuploads%2F7quw6Du3fFg1jyv7nGAQ%2Fimage.png?alt=media\&token=86ea230d-884a-4ac1-8304-58727fe1f054)

### API key (X-API-Key) 

The simplest way to authenticate is to use the HTTP header **X-API-Key** containing the private part of your API key, as in the example below:

```bash
curl -X 'GET' \
  'https://api.dastra.eu/me' \
  -H 'accept: */*' \
  -H 'X-API-Key: <your private key here>'

```

### OAuth2 "Authorization code" flow

#### Authorization

The authorization phase is performed by calling the following URL:

```bash
https://account.dastra.eu/connect/authorize?
    response_type=code&
    client_id={YOUR_CLIENT_ID}&
    redirect_uri=https://YOUR_APP/callback&
    scope=api1+offline_access&
    state={STATE}
```

**Parameters**

| Parameter Name  | Description                                                                                                                                                                                                                                                                                     |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_type` | code                                                                                                                                                                                                                                                                                            |
| `client_id`     | The public key of your API key configured in your Dastra account                                                                                                                                                                                                                                |
| `redirect_uri`  | The URL configured in the Dastra API key. You will be automatically redirected to this page at the end of the authorization process                                                                                                                                                             |
| `scope`         | <p><code>api1</code> => mandatory<br><code>offline\_access</code> => to obtain a refresh\_token (long sessions)</p>                                                                                                                                                                             |
| `state`         | A random string generated by your application to prevent cross-site request forgery (CSRF) attacks. See [Mitigate CSRF Attacks With State Parameters](https://auth0.com/docs/protocols/oauth2/mitigate-csrf-attacks?utm_source=chatgpt.com). Client libraries usually handle this automatically |

### OAuth2 "Client credentials" flow

#### Authentication method

API authentication is based on the [OAuth2 protocol](https://oauth.net/2/?utm_source=chatgpt.com) using the "Client credentials" flow. This authentication mode should only be used for server-to-server requests and must never be used on the client side (e.g., JavaScript SPA).

<figure><img src="https://2697025545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LvBxs22wUMicv9uWp6C-1972196547%2Fuploads%2Fglwo78n9q0Ss98sXgJhL%2Fimage.png?alt=media&#x26;token=46f92473-c260-4ef0-aa9d-93d3dc2d54a3" alt=""><figcaption></figcaption></figure>

#### Getting the token

`POST` `https://account.dastra.eu/connect/token`

Perform a token request using BASIC headers.

**Headers**

| Name          | Type                                       | Description |
| ------------- | ------------------------------------------ | ----------- |
| Authorization | Basic {base64("{PublicKey}:{PrivateKey}")} |             |

**Request Body**

| Name        | Type   | Description         |
| ----------- | ------ | ------------------- |
| grant\_type | string | client\_credentials |
| scope       | string | api1                |

{% tabs %}
{% tab title="200: OK - Access Token for REST API Operations" %}

```json
{
  "access_token": "tNQoqsSePv0DnSSNVJv1aDxzSFh9H2z3YBKtuBKqWAU",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "api1"
}
```

{% endtab %}
{% endtabs %}

Once you have retrieved an access\_token, you can call any REST API endpoint using this token as a "Bearer token".

For example, to get the list of your workspaces:

`GET` `https://api.dastra.eu/v1/workspaces`

Retrieve the list of Dastra workspaces.

**Headers**

| Name          | Type                   | Description |
| ------------- | ---------------------- | ----------- |
| Authorization | Bearer {access\_token} |             |

{% tabs %}
{% tab title="200: OK" %}

```json
{
  "items": [
    {
      "id": 1,
      "tenantId": 1,
      "label": "My data company",
      "logoUrl": null,
      "state": "Active",
      "permissions": null,
      "dataSubjectArchivedRetentionDays": null,
      "nbEntities": 1
    },
    {
      "id": 2,
      "tenantId": 1,
      "label": "My test workspace",
      "logoUrl": null,
      "state": "Active",
      "permissions": null,
      "dataSubjectArchivedRetentionDays": null,
      "nbEntities": 1
    },
    {
      "id": 3,
      "tenantId": 1,
      "label": "My experimentation workspace",
      "logoUrl": null,
      "state": "Active",
      "permissions": null,
      "dataSubjectArchivedRetentionDays": null,
      "nbEntities": 0
    }
  ],
  "total": 3
}
```

{% endtab %}
{% endtabs %}

All requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure?utm_source=chatgpt.com) and always from the server side. Requests without authentication will fail with error code 401.

See the API reference here: [https://api.dastra.eu/swagger/index.html](https://api.dastra.eu/swagger/index.html?utm_source=chatgpt.com)