Authentification

Les clés font 60 caractères, préfixées par l'environnement et encodées en base32 pour la lisibilité :

text
ak_live_AB7K2LJ8MZ4X3WQ9VYTC5H6NPRDFG8EJUSKBHMV2YXQW3TKRP4DL
ak_test_NC9PQ2MJ8MZ4X3WQ9VYTC5H6NPRDFG8EJUSKBHMV2YXQW3TKRPAA

Les clés live s'exécutent dans l'environnement de production. Les clés test sont pour la CI et le développement local. Le préfixe détermine le contexte de tenant dans lequel la clé s'exécute, mais les deux peuvent appeler les mêmes capabilities.

Seuls les quatre premiers caractères après le préfixe d'environnement (ex. example) sont stockés en clair pour l'affichage. Le reste est haché au repos ; si vous perdez une clé, vous devez en créer une nouvelle.

Attachez-la comme header header sur chaque requête. L'API rejette les clés dans les query strings, cookies ou corps JSON.

http
GET /api/v2/vault/projects HTTP/1.1
Host: api.alloovium.com
Authorization: Bearer ak_live_AB7K2LJ8MZ4X3WQ9VYTC5H6NPRDFG8EJUSKBHMV2YXQW3TKRP4DL
Accept: application/json

Si le header est manquant, malformé, révoqué, expiré ou ne correspond à aucune clé, l'API retourne code avec un header header et l'un de ces codes :

Créez une nouvelle clé, basculez le trafic, puis révoquez l'ancienne. Les deux peuvent coexister, donc la rotation sans interruption est simple. La révocation est immédiate — en quelques secondes dans toutes les régions.

Chaque client OAuth commence par récupérer les métadonnées du serveur d'autorisation :

bash
curl https://api.alloovium.com/.well-known/oauth-authorization-server

json
{
  "issuer": "https://api.alloovium.com",
  "authorization_endpoint": "https://api.alloovium.com/api/v2/oauth/authorize",
  "token_endpoint": "https://api.alloovium.com/api/v2/oauth/token",
  "revocation_endpoint": "https://api.alloovium.com/api/v2/oauth/revoke",
  "registration_endpoint": "https://api.alloovium.com/api/v2/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_basic", "client_secret_post"],
  "scopes_supported": [
    "vault:read", "chat:read", "templates:read", "workflows:read", "meta:read"
  ]
}

Un document de métadonnées de ressource protégée correspondant (RFC 9728) est servi sur path.

Pas de pré-provisionnement. N'importe quel client peut s'enregistrer lui-même sur path :

bash
curl -sS https://api.alloovium.com/api/v2/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My Claude Desktop Integration",
    "redirect_uris": ["http://127.0.0.1:51234/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'

json
{
  "client_id": "client_d6kQ6ZrW9v3sLx2n2h0k5Q",
  "client_name": "My Claude Desktop Integration",
  "redirect_uris": ["http://127.0.0.1:51234/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "vault:read chat:read templates:read workflows:read meta:read"
}

La Console développeur vous permet de créer des clients PKCE publics et des clients confidentiels avec un secret unique. C'est le chemin recommandé lorsque vous souhaitez un enregistrement de client stable avant de déployer une intégration.

Générez un verifier aléatoire (43–128 chars URL-safe), calculez challenge, puis redirigez l'utilisateur vers l'endpoint d'autorisation :

text
https://api.alloovium.com/api/v2/oauth/authorize
  ?client_id=client_d6kQ6ZrW9v3sLx2n2h0k5Q
  &redirect_uri=http://127.0.0.1:51234/callback
  &response_type=code
  &scope=vault:read%20chat:read
  &state=xyz123
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256

Si l'utilisateur n'est pas déjà connecté, il sera redirigé vers Clerk pour s'authentifier. Après approbation, le navigateur est redirigé vers votre uri avec params.

Échangez le code contre une paire access token + refresh token :

bash
curl -sS https://api.alloovium.com/api/v2/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE_FROM_REDIRECT" \
  -d "client_id=client_d6kQ6ZrW9v3sLx2n2h0k5Q" \
  -d "redirect_uri=http://127.0.0.1:51234/callback" \
  -d "code_verifier=THE_RANDOM_VERIFIER_YOU_GENERATED"

json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_9c1e4e4ebf97a4b5e76cf9c85e2f09bb",
  "scope": "vault:read chat:read"
}

L'access token est un JWT signé avec les claims Échange de token, tid, client_id et scope. Attachez-le comme bearer sur chaque appel API.

bash
curl -sS https://api.alloovium.com/api/v2/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=rt_9c1e4e4ebf97a4b5e76cf9c85e2f09bb" \
  -d "client_id=client_d6kQ6ZrW9v3sLx2n2h0k5Q"

Les refresh tokens tournent à chaque utilisation. L'ancien est immédiatement invalidé, et la réponse contient un nouveau refresh token. Si un token ayant tourné est rejoué, Alloovium révoque toute la chaîne — une défense standard OAuth 2.1 contre le vol de token.

Si votre client enregistré utilise basic ou post, l'endpoint de token exige le secret correspondant sur chaque échange et requête de rafraîchissement. Stockez ce secret côté serveur uniquement.

bash
curl -sS https://api.alloovium.com/api/v2/oauth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=rt_9c1e4e4ebf97a4b5e76cf9c85e2f09bb" \
  -d "client_id=client_d6kQ6ZrW9v3sLx2n2h0k5Q"

Toutes les capabilities n'acceptent pas les tokens OAuth. Certains handlers s'appuient sur des champs ORM complets qui ne sont présents que pour les principaux à clé API ; ceux-là retournent code lorsqu'ils sont appelés avec un Bearer JWT. Vous pouvez vérifier le support sur chaque page de capability ou dans la colonne OAuth de la matrice des capabilities.