# Authentification et clés

> Envoyer une clé sk-moon, la créer, la limiter (expiration, plafond, liste d’IP, Moon Blur), la remplacer ou la révoquer, et les en-têtes de l’API.

Chaque appel de l’API se fait avec une clé `sk-moon-…`. La clé appartient à un workspace : les requêtes sont débitées de son porte-monnaie et suivent ses plafonds et, dans une organisation gérée, ses règles.

## Envoyer la clé

Mettez la clé dans l’en-tête `Authorization`, après `Bearer`. L’en-tête `x-api-key` est aussi accepté.

```bash title="cURL"
curl https://api.realmoon.ai/v1/models \
  -H "Authorization: Bearer $MOONAI_API_KEY"

# Équivalent
curl https://api.realmoon.ai/v1/models \
  -H "x-api-key: $MOONAI_API_KEY"
```

```python title="Python"
import os
from openai import OpenAI

# Le SDK envoie la clé dans l'en-tête Authorization.
client = OpenAI(
    base_url="https://api.realmoon.ai/v1",
    api_key=os.environ["MOONAI_API_KEY"],
)
print([m.id for m in client.models.list()])
```

```javascript title="JavaScript"
import OpenAI from 'openai';

// Le SDK envoie la clé dans l'en-tête Authorization.
const client = new OpenAI({
  baseURL: 'https://api.realmoon.ai/v1',
  apiKey: process.env.MOONAI_API_KEY,
});
const models = await client.models.list();
console.log(models.data.map((m) => m.id));
```

Une requête sans clé, ou avec une clé inconnue, révoquée ou expirée, reçoit `401 invalid_api_key`. Les autres refus liés à la clé (adresse non autorisée, portée, débit) sont décrits dans [Erreurs](https://realmoon.ai/documentation/api/erreurs/#cle).

## Qui gère les clés

Les clés se gèrent dans le portail, onglet « Clés API » ([ouvrir](https://chat.realmoon.ai/settings/developer/keys)). Seuls le propriétaire et les admins du workspace y ont accès. Aucun point d’accès de l’API, appelé avec une clé `sk-moon-…`, ne crée ni ne révoque de clé.

Une clé appartient au workspace, pas à la personne qui l’a créée. Elle cesse de fonctionner :

- quand elle est révoquée ou remplacée, ou quand elle expire ;
- quand le workspace est supprimé ;
- quand le compte du propriétaire du workspace est suspendu (dans la minute).

À chaque création de clé, un e-mail de sécurité est envoyé au propriétaire du workspace et au contact de facturation.

> [!NOTE]
> **Organisations gérées**
>
> Dans une organisation gérée, les règles de l’organisation peuvent interdire les clés d’API ou certains modèles. Une requête refusée par ces règles reçoit `403 org_policy`. Voir [Règles de l’organisation](https://realmoon.ai/documentation/organisations/regles/).

## Créer une clé

1. Dans « Clés API », sous « Créer une clé API », saisissez un « Nom » (128 caractères au plus), par exemple « backend de production ».
2. Ouvrez « Options avancées » si vous voulez limiter la clé (tableau ci-dessous).
3. Cliquez sur « Créer une clé ».
4. Dans la fenêtre « Enregistrez votre clé API », copiez la clé, puis cliquez sur « J’ai enregistré ma clé ». Si vous fermez la fenêtre sans copier, Moon AI demande « Fermer sans copier votre clé ? » : la clé ne sera plus jamais affichée.

| Réglage | Libellé | Effet |
| --- | --- | --- |
| Expiration | « Expire dans (jours) » | La clé cesse de fonctionner après ce nombre de jours (`401 invalid_api_key`). Vide : « Jamais ». |
| Plafond de dépense | « Plafond de dépense (€) » et « Période » (« par heure », « par jour », « par mois ») | Plafond propre à la clé, sur une fenêtre glissante d’une heure, de 24 heures ou de 30 jours. Au-delà : `402 spend_cap_exceeded` avec `scope: "key"`. Vide : « Aucune limite ». |
| Liste d’IP | « Liste d’IP autorisées » | Adresses IPv4 ou IPv6, ou plages CIDR, séparées par des virgules (par exemple `1.2.3.4, 10.0.0.0/8`). Une requête venue d’ailleurs reçoit `403 ip_not_allowed`. Vide : toutes les adresses. |

Le plafond et la liste d’IP se fixent à la création. Pour les changer, créez une nouvelle clé avec les bons réglages, mettez à jour vos applications, puis révoquez l’ancienne.

> [!WARNING]
> **Liste d’IP**
>
> L’adresse vérifiée est l’adresse publique depuis laquelle votre serveur sort sur Internet. Une entrée mal écrite est ignorée ; si aucune entrée de la liste n’est valide, toutes les requêtes de la clé sont refusées.

## La liste des clés

Sous « Vos clés », chaque ligne montre :

- le début et la fin de la clé (`sk-moon-...a1b2`), pour la reconnaître ;
- « Créée le », « Expire le » et les badges « Expire bientôt » ou « Clé expirée » ;
- « Dernière utilisation » et le nombre de « Requêtes » (mis à jour au plus une fois par minute) ;
- le plafond de dépense et sa période, et « Moon Blur désactivé » le cas échéant.

## Régler une clé

Le bouton « Réglages de la clé » d’une ligne ouvre :

- « Nom de la clé » et « Enregistrer le nom » ;
- l’interrupteur « Moon Blur », activé par défaut.

Moon Blur masque les données personnelles détectées (e-mails, numéros de téléphone, coordonnées bancaires, numéros d’identité) avant que la requête n’arrive chez le fournisseur du modèle, et les remet dans la réponse. Ne le désactivez que si votre application a besoin de ces données elles-mêmes, par exemple pour les extraire d’un document. Moon AI demande confirmation (« Désactiver Moon Blur pour cette clé ? ») et note le changement dans le journal d’audit du workspace. Voir [Confidentialité](https://realmoon.ai/documentation/api/confidentialite/).

## Remplacer une clé

Le bouton « Remplacer la clé » crée une nouvelle clé avec les mêmes réglages et la même durée de validité. L’ancienne cesse de fonctionner immédiatement : mettez à jour vos applications avec la nouvelle, affichée une seule fois. Pour une clé expirée, le bouton s’appelle « Renouveler la clé » et fait la même chose.

Pour remplacer une clé sans interruption, créez plutôt une seconde clé, déployez-la, puis révoquez la première.

## Révoquer une clé

Le bouton « Révoquer la clé » arrête la clé immédiatement pour toutes les applications qui l’utilisent. L’action est irréversible.

> [!WARNING]
> **Clé exposée**
>
> Si une clé a été publiée (dépôt Git, journal, capture d’écran), révoquez-la tout de suite, puis vérifiez « Utilisation » › « Journal des requêtes » pour repérer les appels qui ne viennent pas de vous.

## Portée de la clé

Une clé porte des portées (`scopes`). Toutes les clés créées dans le portail ont la portée `inference`, exigée par tous les points d’accès de l’API, y compris `/v1/models` et `/v1/credits`. Une clé sans elle reçoit `403 missing_scope`.

## Bonnes pratiques

- Une clé par application et par environnement : vous pouvez en révoquer une sans arrêter les autres.
- La clé reste côté serveur : jamais dans le code d’une page web ni d’une application mobile distribuée.
- Lisez la clé dans une variable d’environnement ou un gestionnaire de secrets, jamais en dur dans le code.
- Pour un serveur à adresse fixe, ajoutez une liste d’IP. Pour borner un risque, ajoutez un plafond de dépense à la clé et des plafonds au workspace (onglet « Limites »).
- Fixez une expiration aux clés temporaires (tests, prestataires).

## En-têtes

### En-têtes de requête

| En-tête | Rôle |
| --- | --- |
| `Authorization: Bearer sk-moon-…` | Clé de l’API. |
| `x-api-key: sk-moon-…` | Autre façon d’envoyer la clé. |
| `Content-Type` | `application/json`, ou `multipart/form-data` pour un envoi de fichier. |
| `Content-Length` | Obligatoire pour un envoi `multipart/form-data` (sinon `411 length_required`). curl et les SDK l’envoient. |

### En-têtes de réponse

| En-tête | Valeurs | Présent sur |
| --- | --- | --- |
| `X-Moon-Request-Id` | `gen-…` | Toute requête acceptée. Identifiant à passer à `GET /v1/generation?id=…`. |
| `X-Moon-Prompt-Storage` | `none` | Toute requête acceptée : le contenu n’est pas conservé. |
| `X-Moon-Blur` | `on`, `off` | Conversation et embeddings : Moon Blur a analysé la requête (`on`) ou il est désactivé pour la clé (`off`). |
| `X-Moon-Blur` | `not_applied` | Images, vidéos, voix, transcription : Moon Blur ne s’applique pas à ces contenus. |
| `X-Moon-Blur` | `not_needed` | OCR : le document ne quitte pas nos serveurs. |
| `X-Moon-Blur-Redactions` | nombre | Quand Moon Blur a remplacé des valeurs : leur nombre. |
| `X-Moon-Credits` | nombre | Voix et transcription : crédits facturés pour la requête. |
| `X-Moon-Hosting` | `fr` | OCR : traité sur nos serveurs en France. |
| `Cache-Control` | `no-store` | Réponses des médias et des vidéos. |
| `Retry-After` | secondes | Certaines erreurs `429` et `503` : délai avant de réessayer. |

Pour lire les en-têtes avec un SDK :

```bash title="cURL"
curl -i https://api.realmoon.ai/v1/chat/completions \
  -H "Authorization: Bearer $MOONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-haiku-4.5", "messages": [{"role": "user", "content": "Bonjour"}]}'
```

```python title="Python"
raw = client.chat.completions.with_raw_response.create(
    model="anthropic/claude-haiku-4.5",
    messages=[{"role": "user", "content": "Bonjour"}],
)
print(raw.headers.get("x-moon-request-id"), raw.headers.get("x-moon-blur"))
completion = raw.parse()
```

```javascript title="JavaScript"
const { data: completion, response } = await client.chat.completions
  .create({
    model: 'anthropic/claude-haiku-4.5',
    messages: [{ role: 'user', content: 'Bonjour' }],
  })
  .withResponse();
console.log(response.headers.get('x-moon-request-id'), response.headers.get('x-moon-blur'));
```

---

Documentation Moon AI › API développeur › Authentification. Page : https://realmoon.ai/documentation/api/authentification/. Modifiée le 5 novembre 2026.

© 2026 Stellarr Studio SAS. Tous droits réservés. Moon AI, Moon Blur et Stellarr Studio sont des marques déposées à l’INPI.