> For the complete documentation index, see [llms.txt](https://doc.dastra.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.dastra.eu/en/api/authentication.md).

# Authentication

Learn how to authenticate with Dastra API.

## Getting your API secret key

The Dastra REST API uses API keys to authenticate each request. You manage your keys in the **Api keys & MCP** page, which is reserved to organization owners. See [API key management](https://doc.dastra.eu/en/features/settings/api-keys.md).

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

An API key gives access to your data, so keep it safe. Do not share your private key in public parts of applications, such as GitHub or client-side code.

An expired or unknown key is refused with status 401.

If you want to use OAuth2 authentication with the "authorization\_code" flow, enter the redirect URIs and the allowed CORS origins in the details panel of the key.

<figure><img src="https://2697025545-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LvBxs22wUMicv9uWp6C-1972196547%2Fuploads%2Fgit-blob-b10f737eaaf6b856cb0df152fa2c9334b1921e4c%2Fsettings-api-keys-1.png?alt=media" alt="The API key creation window with the name, workspace, expiration and permissions"><figcaption><p>Creating an API key</p></figcaption></figure>

## 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). Client libraries usually handle this automatically |

## OAuth2 "Client credentials" flow

### Authentication method

API authentication is based on the [OAuth2 protocol](https://oauth.net/2/) 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%2Fgit-blob-8528b96d49b30bf395aa9cdf5fa058207f863c65%2Fapi-authentication-scheam.svg?alt=media" alt="Diagram of the Client credentials flow: your server requests a token from the Dastra identification server, then calls the API with that token"><figcaption><p>The Client credentials flow</p></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) 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>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.dastra.eu/en/api/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
