> For the complete documentation index, see [llms.txt](https://guides.ia.numerique.gouv.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guides.ia.numerique.gouv.fr/albert-api/compte-and-usage/api-keys.md).

# Clés API

Les clés d’API Albert sont gérées sous **`/v1/me/keys`**. Elles servent de **jetons Bearer** pour toutes les routes protégées.

## Format des jetons

Les secrets d’accès sont souvent préfixés par **`sk-`** et peuvent correspondre à un **JWT** encodé (contenant typiquement des identifiants utilisateur et de clé). Traitez la chaîne complète comme **opaque** : ne la parsez pas côté client pour la logique métier.

## Créer une clé — `POST /v1/me/keys`

Corps JSON **`CreateKey`** :

* **`name`** (requis) — libellé pour retrouver la clé dans les listes ;
* **`expires`** — horodatage Unix **en secondes** après lequel la clé n’est plus valide, ou `null` pour absence d’expiration explicite.

Réponse **`CreateKeyResponse`** :

* **`id`** — identifiant entier de la clé ;
* **`token`** — secret **affiché intégralement une seule fois** à la création (selon configuration / environnement).

{% hint style="danger" %}
Le champ **`token`** n’est pas récupérable après coup par l’API documentée : enregistrez-le dans un coffre-fort de secrets (`ALBERT_API_KEY`, gestionnaire d’identifiants, vault). Toute perte implique la révocation et la création d’une nouvelle clé.
{% endhint %}

{% hint style="warning" %}
⚠️ Comportement observé en test (runner) : `POST /v1/me/keys` peut renvoyer **uniquement** `id` (sans `token`). Dans ce cas, la méthode recommandée pour récupérer une nouvelle clé utilisable est de la générer via le **Playground** (qui affiche la clé une seule fois), puis de la stocker en lieu sûr.
{% endhint %}

### Exemple

{% tabs %}
{% tab title="curl" %}

```bash
curl -sS "https://albert.api.etalab.gouv.fr/v1/me/keys" \
  -H "Authorization: Bearer $ALBERT_EXISTANT" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-github", "expires": null}'
```

{% endtab %}

{% tab title="Python" %}

```python
import os
import requests

resp = requests.post(
    "https://albert.api.etalab.gouv.fr/v1/me/keys",
    headers={
        "Authorization": f"Bearer {os.environ['ALBERT_EXISTANT']}",
        "Content-Type": "application/json",
    },
    json={"name": "ci-github", "expires": None},
)
resp.raise_for_status()
print(resp.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const resp = await fetch("https://albert.api.etalab.gouv.fr/v1/me/keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ALBERT_EXISTANT}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "ci-github", expires: null }),
});

if (!resp.ok) throw new Error(await resp.text());
console.log(await resp.json());
```

{% endtab %}
{% endtabs %}

## Lister les clés — `GET /v1/me/keys`

Retourne une liste paginée (`offset`, `limit`, `order_by`, `order_direction`) d’objets **`Key`** (`id`, `name`, `token`, `expires`, `created`, …). Le champ `token` est présent dans le schéma public — **traitez toute valeur affichée comme sensible** et ne la journalisez pas côté client public.

{% hint style="warning" %}
⚠️ À vérifier — Politique réelle de masquage du secret sur les réponses `GET` en production (affichage complet vs préfixe) : valider sur votre compte avant d’afficher la liste à des utilisateurs finaux.
{% endhint %}

## Détail — `GET /v1/me/keys/{key}`

Consultation d’une entrée précise ; `key` est l’**identifiant entier** de la clé.

## Révoquer — `DELETE /v1/me/keys/{key}`

Supprime la clé identifiée par son **`id`**. Réponse **`204`** sans corps en cas de succès.

Pour le profil utilisateur (budget, limites) : [Quotas & limites](/albert-api/compte-and-usage/quotas.md).


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://guides.ia.numerique.gouv.fr/albert-api/compte-and-usage/api-keys.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.