# Authentification

Chaque demande est authentifiée par une **clé API espace de travail**, envoyé comme jeton au porteur:

```
Authorization: Bearer maetra_xxxxxxxxxxxxxxxxxxxx
```

Les clés commencent par `maetra_`C'est vrai. Une clé appartient à un espace de travail et porte un ensemble fixe de **champ d'application**C'est vrai. La même clé authentifie la [API REST](https://maetra.io/fr/docs/getting-started/quickstart) et les [Serveur MCP](https://maetra.io/fr/docs/mcp-server/overview-and-connection).

### Créer une clé API (dans le tableau de bord)

1. Ouvrez le tableau de bord d'Maetra et allez à **Paramètres → touches d'API**.
2. Cliquez sur **Créer la clé API**.
3. Remplissez le dialogue & #160;:
   * **Nom de la clé** — une étiquette pour la reconnaître ultérieurement, par exemple `Production FinanceAgent`.
   * **Portées d'accès** — choisir **Accès complet**ou **Portées personnalisées** choisir par module (Discover, Comply, Govern, Secure, Audit, Task Guard). Accorder le moins d'un besoin clé — voir [Portée](#scopes) ci-dessous.
   * **Restrictions en matière de propriété intellectuelle** *(facultatif)* — une ou plusieurs plages IP/CIDR dont la clé peut être utilisée, par exemple: `192.168.1.0/24`.
4. Cliquez sur **Créer**C'est vrai. La clé complète est affichée **une fois** — touché **Copier la clé**, rangez-le dans un gestionnaire secret, alors **J'ai sauvé ma clé.**.

> **Important**
> Maetra ne stocke qu'un hachage de la clé et ne peut plus la montrer. Si une clé est perdue ou divulguée, **la révoquer et en créer un nouveau** - vous ne pouvez pas le récupérer.


### Portée

Les champs d'application sont vérifiés par demande. Un appel revient `403 Forbidden` si la clé est valide mais n'a pas la portée requise.

| Portée | Subventions |
| -------------------------- | ------------------------------ |
| `govern:checkpoints:write` | Créer des points de contrôle |
| `govern:checkpoints:read` | Points de contrôle de la lecture / à longue portée |
| `govern:policies:read` | Énumérer les politiques actives |
| `secure:scan:write` | Contenu de l'analyse |
| `secure:rules:read` | Liste des règles Secure |
| `secure:rules:write` | Créer et mettre à jour les règles Secure |
| `secure:incidents:read` | Liste des incidents |
| `discover:agents:read` | Liste des agents enregistrés |
| `task_guard:tasks:write` | Démarrer, mettre à jour, arrêter, reprendre, annuler et terminer les tâches d'Task Guard |
| `task_guard:tasks:read` | Récupérer le contexte actif de la tâche Task Guard |
| `task_guard:checks:write` | Vérifier l'alignement de l'action et expliquer les relations de tâches |
| `task_guard:effects:write` | Signaler et comparer les effets réels de l'action |
| `task_guard:confirmations:write` | Soumettre des événements d'hôte de confiance et des confirmations de portée |

#### Cartes sauvages

Une clé peut contenir des champs wildcard : `*` (tout), ou un préfixe de module comme `govern:*` / `secure:*` / `discover:*` / `task_guard:*`C'est vrai. Le tableau de bord **Accès complet** Aides `*`; choisir un module entier sous **Portées personnalisées** octroie ce module `*`.

> **Note**
> `task_guard:confirmations:write` est nécessaire mais ne suffit pas pour les événements d'accueil de confiance et les confirmations de portée en ligne. La clé API doit également être marquée comme un justificatif de confirmation Task Guard de confiance pour l'espace de travail.


### Vérifiez une clé

Utilisation `GET /v1/ping` pour confirmer une clé est valide et voir ses champs d'application:

#### 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"] }
```

### Récupérer une clé

Récupérer une clé de **Paramètres → touches d'API** (le menu des actions de la ligne). Révocation immédiate — nouvelles demandes de retour `401 Unauthorized`C'est vrai. La révocation d'une clé n'affecte jamais les autres.

Voir [Erreurs et limites de taux](https://maetra.io/fr/docs/getting-started/errors-and-rate-limits) pour le format d'erreur complet.