Aller au contenu
KelkiDéveloppeurs

OAuth

Jeton OAuth 2.0 « client credentials » (RFC 6749 § 4.4) et révocation (RFC 7009).

Adresse de base : https://kelki.ai/api/v1.

POST /oauth/token

Obtenir un jeton d'accès (client credentials)

Échange client_id + client_secret (HTTP Basic, RFC 6749 § 2.3.1) contre un jeton opaque de 15 minutes. Les portées demandées doivent être accordées au client. Le mode (test / live) est celui du client.

Authentification : identifiants du client OAuth (HTTP Basic).

Corps de la requête

application/x-www-form-urlencoded — TokenRequest (obligatoire)

{
  "grant_type": "client_credentials",
  "scope": "catalog.read requests.write requests.read"
}

Réponses

CodeDescriptionContenu
200

Jeton délivré.

application/json TokenResponse
400

Requête invalide (RFC 6749 § 5.2).

application/json OAuthError
401

Client inconnu, secret invalide ou révoqué.

application/json OAuthError
429

Débit ou quota dépassé.

application/problem+json Problem

Exemple de réponse

{
  "access_token": "kat_test_EXEMPLE0000000000000000000000000000000",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "catalog.read requests.write requests.read"
}

POST /oauth/revoke

Révoquer un jeton d'accès (RFC 7009)

Authentification : identifiants du client OAuth (HTTP Basic).

Corps de la requête

application/x-www-form-urlencoded — RevokeRequest (obligatoire)

Réponses

CodeDescriptionContenu
200

Jeton révoqué (réponse identique si le jeton était déjà invalide, RFC 7009 § 2.2).

401

Client inconnu ou secret invalide.

application/json OAuthError

Schémas

TokenRequest

ChampTypeRequisDescription
grant_typestringoui

valeur : client_credentials

scopestringnon

Portées séparées par des espaces. Par défaut, toutes les portées accordées au client.

TokenResponse

ChampTypeRequisDescription
access_tokenstringoui
token_typestringoui

valeur : Bearer

expires_inintegeroui

Durée de validité en secondes.

scopestringoui

OAuthError

ChampTypeRequisDescription
errorstringoui

valeurs : invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope

error_descriptionstringnon

Problem

Détails d'un problème (RFC 9457), avec des membres d'extension.

ChampTypeRequisDescription
typestring (uri)oui

URI stable du type de problème ; elle mène à sa documentation.

titlestringoui
statusintegeroui

min. 400 · max. 599

detailstringnon
instancestring (uri-reference)non
codestringoui

Code stable, lisible par une machine.

valeurs : invalid_json, invalid_parameter, payload_too_large, unsupported_media_type, invalid_credentials, expired_token, insufficient_scope, live_not_enabled, account_suspended, country_not_available, trade_not_available, not_found, invalid_state, idempotency_in_progress, idempotency_key_reused, validation_failed, consent_missing, consent_version_outdated, contact_limit_reached, duplicate_request, rate_limited, quota_exceeded, agent_paused, live_creation_paused, service_unavailable, internal_error

request_idstringoui
errorstableau de FieldErrornon

RevokeRequest

ChampTypeRequisDescription
tokenstringoui
token_type_hintstringnon

valeurs : access_token

FieldError

ChampTypeRequisDescription
pointerstringoui

JSON Pointer (RFC 6901) du champ en cause.

detailstringoui
allowedtableau de stringnon

Valeurs acceptées, quand la liste est fermée.