# Authentifizierung

Jede Anfrage wird authentifiziert mit einem **Workspace API Schlüssel**, als Bearer-Token gesendet:

```
Authorization: Bearer maetra_xxxxxxxxxxxxxxxxxxxx
```

Keys beginnen mit `maetra_`. Ein Schlüssel gehört zu einem Arbeitsbereich und trägt einen festen Satz von **Geltungsbereiche**. Der gleiche Schlüssel authentifiziert die [REST API](https://maetra.io/de/docs/getting-started/quickstart) und die [MCP Server](https://maetra.io/de/docs/mcp-server/overview-and-connection).

### Erstellen eines API-Schlüssels (im Dashboard)

1. Öffnen Sie das Maetra-Dashboard und gehen Sie zu **Einstellungen → API Keys**.
2. Klicken **API-Key erstellen**.
3. Füllen Sie den Dialog aus:
   * **Schlüsselbezeichnung** - ein Label, um es später zu erkennen, z.B. `Production FinanceAgent`.
   * **Zugangsbereiche** — wählen **Vollständiger Zugang**, oder **Zollrechtliche Geltungsbereiche** pro Modul auswählen (Discover, Comply, Govern, Secure, Audit, Task Guard). Gewähren Sie den geringsten Schlüsselbedürfnissen - siehe [Anwendungsbereiche](#scopes) unten.
   * **IP-Beschränkungen** *(fakultativ)* Ein oder mehrere IPs/CIDR-Bereiche, aus denen der Schlüssel verwendet werden kann, z.B. `192.168.1.0/24`.
4. Klicken **Schaffen**. Der vollständige Schlüssel wird angezeigt **einmal** — Treffer **Kopierschlüssel**, speichern Sie es in einem geheimen Manager, dann **Ich habe meinen Schlüssel gespeichert**.

> **Important**
> Maetra speichert nur einen Hash des Schlüssels und kann ihn nie wieder zeigen. Wenn ein Schlüssel verloren geht oder durchgesickert ist, **Entziehen Sie es und erstellen Sie ein neues** - Sie können es nicht wiederherstellen.


### Anwendungsbereiche

Scopes werden pro Anfrage überprüft. Ein Call Return `403 Forbidden` wenn der Schlüssel gültig ist, aber der erforderliche Umfang fehlt.

| Anwendungsbereich | Zuschüsse |
| -------------------------- | ------------------------------ |
| `govern:checkpoints:write` | Checkpoints erstellen |
| `govern:checkpoints:read` | Lesen / Long-Poll Checkpoints |
| `govern:policies:read` | Aktive Politiken auflisten |
| `secure:scan:write` | Scan-Inhalte |
| `secure:rules:read` | Secure Regeln auflisten |
| `secure:rules:write` | Erstellen und Aktualisieren von Secure-Regeln |
| `secure:incidents:read` | Auflistung der Vorfälle |
| `discover:agents:read` | Liste der registrierten Agenten |
| `task_guard:tasks:write` | Starten, Aktualisieren, Anhalten, Fortsetzen, Abbrechen und Abschließen von Task Guard-Aufgaben |
| `task_guard:tasks:read` | Aktiver Task Guard Aufgabenkontext abrufen |
| `task_guard:checks:write` | Überprüfen Sie die Handlungsausrichtung und erklären Sie Aufgabenbeziehungen |
| `task_guard:effects:write` | Berichten und Vergleichen der tatsächlichen Wirkung |
| `task_guard:confirmations:write` | Senden Sie vertrauenswürdige Host-Benutzerereignisse und Umfangsbestätigungen |

#### Wildcards

Ein Schlüssel kann Wildcard-Bereiche enthalten: `*` (alles) oder ein Modulpräfix wie `govern:*` / `secure:*` / `discover:*` / `task_guard:*`. Das Armaturenbrett **Vollständiger Zugang** Zuschüsse `*`; Auswahl eines ganzen Moduls unter **Zollrechtliche Geltungsbereiche** gewährt dieses Moduls `*`.

> **Note**
> `task_guard:confirmations:write` ist notwendig, aber nicht ausreichend für vertrauenswürdige Host-Events und Inline-Ergebnisse. Der API-Schlüssel muss auch als vertrauenswürdiger Task Guard-Bestätigungsnachweis für den Arbeitsbereich markiert werden.


### Überprüfen Sie einen Schlüssel

Verwendung `GET /v1/ping` um zu bestätigen, dass ein Schlüssel gültig ist und seine Anwendungsbereiche sehen:

#### cURL

```bash
curl "https://api.maetra.io/v1/ping" \
  -H "Authorization: Bearer $MAETRA_API_KEY"
```

#### JavaScript

```javascript
const res = await fetch("https://api.maetra.io/v1/ping", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = await res.json();
console.log(data);
```

#### TypeScript

```typescript
const res = await fetch("https://api.maetra.io/v1/ping", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.MAETRA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Maetra API ${res.status}`);
const data = (await res.json());
```

#### Python

```python
import os, requests

res = requests.get(
    "https://api.maetra.io/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['MAETRA_API_KEY']}"},
)
res.raise_for_status()
print(res.json())
```

#### Rust

```rust
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let key = std::env::var("MAETRA_API_KEY")?;
    let client = reqwest::Client::new();
    let res = client
        .get("https://api.maetra.io/v1/ping")
        .bearer_auth(&key)
        .send()
        .await?;
    let data: serde_json::Value = res.json().await?;
    println!("{data:#}");
    Ok(())
}
```

#### C++

```cpp
#include <curl/curl.h>
#include <cstdlib>
#include <string>

int main() {
    CURL* curl = curl_easy_init();
    std::string auth = "Authorization: Bearer " + std::string(std::getenv("MAETRA_API_KEY"));
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, auth.c_str());
    curl_easy_setopt(curl, CURLOPT_URL, "https://api.maetra.io/v1/ping");
    curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
    curl_easy_perform(curl);   // response is written to stdout by default
    curl_slist_free_all(headers);
    curl_easy_cleanup(curl);
    return 0;
}
```

#### Java

```java
import java.net.URI;
import java.net.http.*;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.maetra.io/v1/ping"))
    .header("Authorization", "Bearer " + System.getenv("MAETRA_API_KEY"))
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();
var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```


```json
{ "ok": true, "workspace_id": "ws_3Nf9k2", "scopes": ["govern:checkpoints:write"] }
```

### Einen Schlüssel widerrufen

Entziehen Sie einen Schlüssel von **Einstellungen → API Keys** (Aktionsmenü der Zeile). Widerruf ist sofort — weitere Anfragen Rückkehr `401 Unauthorized`. Das Widerrufen eines Schlüssels hat nie Auswirkungen auf die anderen.

Siehe [Fehler & Rate Limits](https://maetra.io/de/docs/getting-started/errors-and-rate-limits) für das vollständige Fehlerformat.