> 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/de/api/authentication.md).

# Authentifizierung

Erfahren Sie, wie Sie sich bei der Dastra-API authentifizieren.

## Ihren geheimen API-Schlüssel abrufen

Die Dastra-REST-API verwendet API-Schlüssel, um jede Anfrage zu authentifizieren. Sie verwalten Ihre Schlüssel auf der Seite **API-Schlüssel & MCP**, die den Inhabern der Organisation vorbehalten ist. Siehe [API-Schlüssel verwalten](https://doc.dastra.eu/de/features/settings/api-keys.md).

Sie können einen API-Schlüssel für einen bestimmten Mandanten oder für die gesamte Organisation verwenden.

Ein API-Schlüssel gewährt Zugriff auf Ihre Daten, bewahren Sie ihn daher sicher auf. Teilen Sie Ihren privaten Schlüssel nicht in öffentlichen Bereichen von Anwendungen, etwa auf GitHub oder in clientseitigem Code.

Ein abgelaufener oder unbekannter Schlüssel wird mit dem Status 401 abgelehnt.

Wenn Sie die OAuth2-Authentifizierung mit dem Ablauf „authorization\_code“ verwenden möchten, tragen Sie die Weiterleitungs-URIs und die erlaubten CORS-Ursprünge im Detailbereich des Schlüssels ein.

<figure><img src="https://1094947073-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgG4SiA7dB1sjSI91cItk%2Fuploads%2Fgit-blob-b10f737eaaf6b856cb0df152fa2c9334b1921e4c%2Fsettings-api-keys-1.png?alt=media" alt="Das Fenster zum Erstellen eines API-Schlüssels mit Name, Mandant, Ablaufdatum und Berechtigungen"><figcaption><p>Einen API-Schlüssel erstellen</p></figcaption></figure>

## API-Schlüssel (X-API-Key)

Am einfachsten authentifizieren Sie sich mit dem HTTP-Header **X-API-Key**, der den privaten Teil Ihres API-Schlüssels enthält, wie im folgenden Beispiel:

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

```

## OAuth2-Ablauf „Authorization code“

### Autorisierung

Die Autorisierungsphase wird durch Aufruf der folgenden URL durchgeführt:

```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}
```

**Parameter**

| Parametername   | Beschreibung                                                                                                                                                                                                                                                                                                          |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `response_type` | code                                                                                                                                                                                                                                                                                                                  |
| `client_id`     | Der öffentliche Teil Ihres API-Schlüssels, der in Ihrem Dastra-Konto konfiguriert ist                                                                                                                                                                                                                                 |
| `redirect_uri`  | Die im Dastra-API-Schlüssel konfigurierte URL. Am Ende des Autorisierungsvorgangs werden Sie automatisch auf diese Seite weitergeleitet                                                                                                                                                                               |
| `scope`         | <p><code>api1</code> => erforderlich<br><code>offline\_access</code> => um ein refresh\_token zu erhalten (lange Sitzungen)</p>                                                                                                                                                                                       |
| `state`         | Eine zufällige Zeichenfolge, die Ihre Anwendung erzeugt, um Cross-Site-Request-Forgery-Angriffe (CSRF) zu verhindern. Siehe [Mitigate CSRF Attacks With State Parameters](https://auth0.com/docs/protocols/oauth2/mitigate-csrf-attacks) (auf Englisch). Client-Bibliotheken übernehmen dies in der Regel automatisch |

## OAuth2-Ablauf „Client credentials“

### Authentifizierungsmethode

Die Authentifizierung der API beruht auf dem [OAuth2-Protokoll](https://oauth.net/2/) mit dem Ablauf „Client credentials“. Dieser Authentifizierungsmodus sollte nur für Server-zu-Server-Anfragen verwendet und nie auf der Clientseite eingesetzt werden (zum Beispiel in einer JavaScript-SPA).

<figure><img src="https://1094947073-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FgG4SiA7dB1sjSI91cItk%2Fuploads%2Fgit-blob-8528b96d49b30bf395aa9cdf5fa058207f863c65%2Fapi-authentication-scheam.svg?alt=media" alt="Diagramm des Ablaufs Client credentials: Ihr Server fordert beim Identifikationsserver von Dastra ein Token an und ruft dann die API mit diesem Token auf"><figcaption><p>Der Ablauf Client credentials</p></figcaption></figure>

### Das Token abrufen

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

Senden Sie eine Token-Anfrage mit BASIC-Headern.

**Header**

| Name          | Typ                                        | Beschreibung |
| ------------- | ------------------------------------------ | ------------ |
| Authorization | Basic {base64("{PublicKey}:{PrivateKey}")} |              |

**Anfragetext**

| Name        | Typ    | Beschreibung        |
| ----------- | ------ | ------------------- |
| 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 %}

Sobald Sie ein access\_token abgerufen haben, können Sie jeden Endpunkt der REST-API aufrufen und dieses Token als „Bearer-Token“ verwenden.

Um zum Beispiel die Liste Ihrer Mandanten abzurufen:

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

Ruft die Liste der Dastra-Mandanten ab.

**Header**

| Name          | Typ                    | Beschreibung |
| ------------- | ---------------------- | ------------ |
| 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 %}

Alle Anfragen müssen über [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure) und immer serverseitig erfolgen. Anfragen ohne Authentifizierung scheitern mit dem Fehlercode 401.

Die API-Referenz finden Sie hier: <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/de/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.
