Clés API

Méthodes, champs des requêtes et réponses.

Guide complet

Cette rubrique comporte 5 méthodes. Ouvrez une méthode pour consulter les conditions d’accès, les champs de la requête et la réponse.

Méthode et chemin	Description	Accès
`GET /api/v1/keys`	Liste des clés API	Token de l’espace client
`POST /api/v1/keys`	Création d’une clé API	Token de l’espace client
`DELETE /api/v1/keys/:id`	Suppression d’une clé API	Token de l’espace client
`GET /api/v1/keys/:id`	Récupération d’une clé API par identifiant	Token de l’espace client
`PUT /api/v1/keys/:id`	Modification d’une clé API	Token de l’espace client

GET /api/v1/keys — Liste des clés API

Accès : token de l’espace client

GET/api/v1/keys

Lecture ; l’ID provient de votre réponse précédente

curl --fail-with-body "https://ailoot.ai/api/v1/keys" \
  -H "Authorization: Bearer $TOKEN"

Paramètres de la chaîne de requête

Le champ	Type	Obligatoire	Validation / description
`sort_by`	`string`	non	; par défaut : created_at
`sort_order`	`string`	non	; par défaut : desc
`search`	`string`	non
`status`	`string`	non
`page`	`integer`	non	; par défaut : 1 ; positive ; page_size/limit <=1000
`page_size`	`integer`	non	; par défaut : 20 ; positive ; page_size/limit <=1000
`limit`	`integer`	non	; par défaut : 20 ; positive ; page_size/limit <=1000

Aucun corps de requête n’est nécessaire. Transmettez les paramètres ci-dessus dans l’URL.

Réponse

La réponse JSON contient code, message et data. Le contenu de data est décrit dans les schémas ci-dessous.

Schémas des données de réponse : APIKey. Les champs et les types figurent sur les pages « Schémas de données ».

Schéma de la réponse, avec des valeurs fictives

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "PLACEHOLDER_ID (integer)",
        "user_id": "PLACEHOLDER_USER_ID (integer)",
        "key": "PLACEHOLDER_KEY (string)",
        "name": "PLACEHOLDER_NAME (string)",
        "status": "PLACEHOLDER_STATUS (string)",
        "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
        "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
        "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
        "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
        "quota": "PLACEHOLDER_QUOTA (number)",
        "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
        "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
        "created_at": "PLACEHOLDER_CREATED_AT (string)",
        "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
        "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
        "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
        "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
        "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
        "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
        "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
        "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
        "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
        "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
        "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
        "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
        "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
        "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
        "user": "PLACEHOLDER_USER (object)"
      }
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}

Particularités : toutes les données personnelles et tous les objets sont limités au périmètre du sujet du JWT.

Particularités : la réponse contient la valeur secrète key ; ne publiez pas les valeurs réelles.

POST /api/v1/keys — Création d’une clé API

Accès : token de l’espace client

POST/api/v1/keys

Champs JSON / du formulaire

Le champ	Type	Obligatoire	Validation / description
`name`	`string`	oui	required
`custom_key`	`string`	non	; Valeur personnalisée facultative de la clé ; peut être null
`ip_whitelist`	`array`	non	; Liste des IP autorisées
`ip_blacklist`	`array`	non	; Liste des IP interdites
`quota`	`number`	non	; Plafond de dépenses de la clé en USD ; peut être null
`expires_in_days`	`integer`	non	; Durée de validité en jours ; peut être null
`rate_limit_5h`	`number`	non	; peut être null
`rate_limit_1d`	`number`	non	; peut être null
`rate_limit_7d`	`number`	non	; peut être null

Modèle du corps de la requête

{
  "name": "PLACEHOLDER_NAME (string)",
  "custom_key": "PLACEHOLDER_CUSTOM_KEY (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_in_days": "PLACEHOLDER_EXPIRES_IN_DAYS (integer)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)"
}

PLACEHOLDER représente votre saisie et son type. Remplacez les valeurs et ne conservez que les champs facultatifs nécessaires ; les marqueurs textuels ne doivent pas remplacer des nombres, des booléens (boolean), des objets ou des tableaux.

Schéma de la requête : CreateAPIKeyRequest

Réponse

La réponse JSON contient code, message et data. Le contenu de data est décrit dans les schémas ci-dessous.

Schémas des données de réponse : APIKey. Les champs et les types figurent sur les pages « Schémas de données ».

Schéma de la réponse, avec des valeurs fictives

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Particularités : toutes les données personnelles et tous les objets sont limités au périmètre du sujet du JWT.

Particularités : cette opération modifie l’état ou poursuit une autorisation à usage unique ; l’exemple décrit le contrat et n’est pas exécuté.

Particularités : Idempotency-Key est pris en charge ; un nouvel envoi renvoie la réponse enregistrée avec X-Idempotency-Replayed.

Particularités : la réponse contient la valeur secrète key ; ne publiez pas les valeurs réelles.

DELETE /api/v1/keys/ :id — Suppression d’une clé API

Accès : token de l’espace client

DELETE/api/v1/keys/:id

Paramètres du chemin

Le champ	Type	Obligatoire	Validation / description
`id`	`integer`	oui

Aucun corps de requête n’est nécessaire.

Réponse

La réponse JSON contient code, message et data. Le contenu de data est décrit dans les schémas ci-dessous.

Schéma de la réponse, avec des valeurs fictives

{
  "code": 0,
  "message": "success",
  "data": {
    "message": "VALUE_FROM_RESPONSE"
  }
}

Particularités : toutes les données personnelles et tous les objets sont limités au périmètre du sujet du JWT.

Particularités : cette opération modifie l’état ou poursuit une autorisation à usage unique ; l’exemple décrit le contrat et n’est pas exécuté.

Particularités : la réponse contient la valeur secrète key ; ne publiez pas les valeurs réelles.

GET /api/v1/keys/ :id — Récupération d’une clé API par identifiant

Accès : token de l’espace client

GET/api/v1/keys/:id

Lecture ; l’ID provient de votre réponse précédente

curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \
  -H "Authorization: Bearer $TOKEN"

Paramètres du chemin

Le champ	Type	Obligatoire	Validation / description
`id`	`integer`	oui

Aucun corps de requête n’est nécessaire. Transmettez les paramètres ci-dessus dans l’URL.

Réponse

La réponse JSON contient code, message et data. Le contenu de data est décrit dans les schémas ci-dessous.

Schémas des données de réponse : APIKey. Les champs et les types figurent sur les pages « Schémas de données ».

Schéma de la réponse, avec des valeurs fictives

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Particularités : toutes les données personnelles et tous les objets sont limités au périmètre du sujet du JWT.

Particularités : la réponse contient la valeur secrète key ; ne publiez pas les valeurs réelles.

PUT /api/v1/keys/ :id — Modification d’une clé API

Accès : token de l’espace client

PUT/api/v1/keys/:id

Paramètres du chemin

Le champ	Type	Obligatoire	Validation / description
`id`	`integer`	oui

Champs JSON / du formulaire

Le champ	Type	Obligatoire	Validation / description
`name`	`string`	non
`status`	`string`	non	omitempty,oneof=active inactive
`ip_whitelist`	`array`	non	; IP autorisées : null ne modifie pas la liste, un tableau vide l’efface ; peut être null
`ip_blacklist`	`array`	non	; IP interdites : null ne modifie pas la liste, un tableau vide l’efface ; peut être null
`quota`	`number`	non	; Plafond de dépenses de la clé en USD ; 0 signifie sans plafond ; peut être null
`expires_at`	`string`	non	; Date et heure d’expiration au format ISO 8601 ; peut être null
`reset_quota`	`boolean`	non	; Remettre à zéro la part dépensée du plafond ; peut être null
`rate_limit_5h`	`number`	non	; peut être null
`rate_limit_1d`	`number`	non	; peut être null
`rate_limit_7d`	`number`	non	; peut être null
`reset_rate_limit_usage`	`boolean`	non	; Remettre à zéro les dépenses comptabilisées par fenêtre ; peut être null

Modèle du corps de la requête

{
  "name": "PLACEHOLDER_NAME (string)",
  "status": "PLACEHOLDER_STATUS (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
  "reset_quota": "PLACEHOLDER_RESET_QUOTA (boolean)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
  "reset_rate_limit_usage": "PLACEHOLDER_RESET_RATE_LIMIT_USAGE (boolean)"
}

Schéma de la requête : UpdateAPIKeyRequest

Réponse

La réponse JSON contient code, message et data. Le contenu de data est décrit dans les schémas ci-dessous.

Schémas des données de réponse : APIKey. Les champs et les types figurent sur les pages « Schémas de données ».

Schéma de la réponse, avec des valeurs fictives

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

Particularités : toutes les données personnelles et tous les objets sont limités au périmètre du sujet du JWT.

Particularités : cette opération modifie l’état ou poursuit une autorisation à usage unique ; l’exemple décrit le contrat et n’est pas exécuté.

Particularités : la réponse contient la valeur secrète key ; ne publiez pas les valeurs réelles.

Particularités : tant que la clé a des requêtes en cours avec une réservation, son plafond de dépenses ne peut pas être réduit ni sa consommation remise à zéro. Transmettez uniquement les champs que vous modifiez.

Des questions ? Envoyez-nous le Request ID et une description : nous vous aiderons à y voir plus clair.Contacter l’assistance