Intégration et API

Documentation sur l'API

La documentation relative aux points de terminaison disponibles se trouve à l'adresse suivante : https://api.deval.to/.

Authentification

Pour vous connecter à l'API, vous devez authentifier un utilisateur spécifique dont vous connaissez le mot de passe.

Disons que l'url de LogAlto est https://acme.logalto.com , et que vous voulez authentifier bob@acme.com avec le mot de passe Kj78qc , vous feriez cette requête :

REST:

POST https://acme.logalto.com/api/oauth/v2/token
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=bob@acme.com&password=Kj78qc&client_id=4_12sxbla9pmo000gkw4gwo04w400s8k0gk0kwcs40ksgokw8css&client_secret=4we2yn2wuq04gkcwg8g8kwg8wgwg0swowc0cokg8s4g8k8k8g

Curl:

curl 'https://acme.logalto.com/api/oauth/v2/token' -H 'Content-Type: application/x-www-form-urlencoded' --data 'grant_type=password&username=bob@acme.com&password=Kj78qc&client_id=4_12sxbla9pmo000gkw4gwo04w400s8k0gk0kwcs40ksgokw8css&client_secret=4we2yn2wuq04gkcwg8g8kwg8wgwg0swowc0cokg8s4g8k8k8g'

Pour plus de clarté, les paramètres décodés ci-dessus sont les suivants :

grant_type: password
username: bob@acme.com
password: Kj78qc
client_id: 4_12sxbla9pmo000gkw4gwo04w400s8k0gk0kwcs40ksgokw8css
client_secret: 4we2yn2wuq04gkcwg8g8kwg8wgwg0swowc0cokg8s4g8k8k8g

La réponse à la demande d'authentification se présente comme suit :

{
    "access_token":"YmQxNGRlODVmZDM3Y2MwNzUwODVmZGE2ZmY0OGIwOTQ0OGQ3OWViYWFlNjgyNzlhMjE4M2E1ZDY0NzQ1ZGI3Yg",
    "expires_in":3600,
    "token_type":"bearer",
    "scope":"user",
    "refresh_token":"ZGMyOTI0Y2FkYWNiZjc5YmNmZDkwM2Y5MDNiNmVlMTZmOTRlZmUwMzM3ZTMzYTcwM2Y5NTk2ZWE1NzgwNDY5YQ",
    "password_do_not_comply_with_policy":false
}

Autorisation

Le jeton d'accès renvoyé en réponse à la demande d'authentification ci-dessus doit ensuite être utilisé pour autoriser toutes les demandes d'API ultérieures avec un "Bearer header" comme celui-ci :

REST:

GET https://acme.logalto.com/api/categorizations
Authorization: Bearer YmQxNGRlODVmZDM3Y2MwNzUwODVmZGE2ZmY0OGIwOTQ0OGQ3OWViYWFlNjgyNzlhMjE4M2E1ZDY0NzQ1ZGI3Yg

Curl:

curl 'https://acme.logalto.com/api/categorizations' -H 'Authorization: Bearer YmQxNGRlODVmZDM3Y2MwNzUwODVmZGE2ZmY0OGIwOTQ0OGQ3OWViYWFlNjgyNzlhMjE4M2E1ZDY0NzQ1ZGI3Yg'

Actualiser votre jeton d'accès

Comme vous pouvez le voir dans la réponse à la demande d'authentification, le jeton d'accès expire au bout de 3600 secondes (1 heure). Après cela, vous devez obtenir un nouveau jeton d'accès pour continuer à utiliser l'API. Vous pouvez soit vous réauthentifier, soit rafraîchir votre jeton d'accès avec la commande refresh_token . Dans les deux cas, les requêtes et les réponses sont similaires, à la différence que le rafraîchissement de votre jeton ne nécessite pas l'affichage de votre mot de passe. Voici à quoi ressemblerait la requête pour rafraîchir votre jeton, toujours avec le même exemple :

REST:

POST https://acme.logalto.com/api/oauth/v2/token
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token=ZGMyOTI0Y2FkYWNiZjc5YmNmZDkwM2Y5MDNiNmVlMTZmOTRlZmUwMzM3ZTMzYTcwM2Y5NTk2ZWE1NzgwNDY5YQ&client_id=4_12sxbla9pmo000gkw4gwo04w400s8k0gk0kwcs40ksgokw8css&client_secret=4we2yn2wuq04gkcwg8g8kwg8wgwg0swowc0cokg8s4g8k8k8g

Curl:

curl 'https://acme.logalto.com/api/oauth/v2/token' -H 'Content-Type: application/x-www-form-urlencoded' --data 'grant_type=refresh_token&refresh_token=ZGMyOTI0Y2FkYWNiZjc5YmNmZDkwM2Y5MDNiNmVlMTZmOTRlZmUwMzM3ZTMzYTcwM2Y5NTk2ZWE1NzgwNDY5YQ&client_id=4_12sxbla9pmo000gkw4gwo04w400s8k0gk0kwcs40ksgokw8css&client_secret=4we2yn2wuq04gkcwg8g8kwg8wgwg0swowc0cokg8s4g8k8k8g'

Pour plus de clarté, les paramètres décodés ci-dessus sont les suivants :

grant_type: refresh_token
refresh_token: ZGMyOTI0Y2FkYWNiZjc5YmNmZDkwM2Y5MDNiNmVlMTZmOTRlZmUwMzM3ZTMzYTcwM2Y5NTk2ZWE1NzgwNDY5YQ
client_id: 4_12sxbla9pmo000gkw4gwo04w400s8k0gk0kwcs40ksgokw8css
client_secret: 4we2yn2wuq04gkcwg8g8kwg8wgwg0swowc0cokg8s4g8k8k8g

La réponse à la demande d'authentification se présente comme suit :

{
    "access_token":"ZTliZTBkYWI1MDVlMzRjZTAxMjg1Y2Y4YjU0MzZiYmNkYjkwMTY2OGQzMzZhY2UzMDJhMmJjY2IxMzY2OWMxMw",
    "expires_in":3600,
    "token_type":"bearer",
    "scope":"user",
    "refresh_token":"ZGE0OTNkODM3YzMxNGQ2YTlmN2I2YmU4MDZjM2RmZmQ4M2IyNWIzYmJiOWYyMGNiNDQwMzIzMWQ1MDViMjE5NQ",
    "password_do_not_comply_with_policy":false
}

Comme vous pouvez le voir, cela renvoie un nouveau jeton d'accès ainsi qu'un nouveau jeton de rafraîchissement pour continuer à utiliser l'API pendant une heure et ainsi de suite.

Notez que, même si cela n'est pas précisé dans la réponse, le jeton de rafraîchissement expire également, mais seulement au bout de deux semaines.

Authentification avec JWT

Cette section suppose que vous êtes déjà familiarisé avec les jetons Web JSON.

Activation de l'authentification JWT

  1. Générez une paire de clés RSA avec l'algorithme aes256 et une clé privée de 4096 bits. Voici comment procéder sous Linux avec openssl :
openssl genrsa -aes256 -passout "pass:mypassword" -out private-encrypted.pem 4096
openssl rsa -pubout -in private-encrypted.pem -passin "pass:mypassword" -out public.pem
openssl rsa -in private-encrypted.pem -out private-decrypted.pem -passin "pass:mypassword"
  1. Envoyez-nous votre fichier de clé publique ainsi que les adresses électroniques des utilisateurs existants de LogAlto qui doivent être autorisés à s'authentifier avec cette clé.
  2. Nous vous renverrons les informations nécessaires pour que vous puissiez authentifier ces utilisateurs à l'aide d'un JWT.

S'authentifier après avoir activé l'authentification JWT

  1. Voici l'en-tête et la charge utile JWT nécessaires pour s'authentifier auprès de LogAlto.
  2. En-tête :
{
  "typ": "JWT",
  "alg": "RS256"
}
  1. Charge utile :
{
  "jti": "__Version 4 UUID__",
  "exp": __expires at UNIX timestamp__,
  "iss": "__provided by DevAlto__",
  "sub": "__email of the user__",
  "aud": "__your LogAlto URL__"
}
    • Le jti claim doit être un UUID valide de la version 4. Vous êtes responsable de sa génération.
    • La demande d'exp ne doit pas être trop éloignée dans le temps pour des raisons de sécurité. Notez que le jeton expire dès qu'il est utilisé pour l'authentification, quelle que soit la demande d'exp.
    • Le iss claim est fournie par DevAlto lorsque nous autorisons votre clé publique.
    • Le sub claim peut être n'importe quel courriel d'utilisateur autorisé pour votre clé publique.
    • L'aud claim est l'URL de LogAlto.

  1. Une fois que vous avez votre JWT signé avec les exigences ci-dessus, vous pouvez l'utiliser pour vous authentifier. La requête est similaire à celle documentée plus haut pour un mot de passe, sauf que la clé de mot de passe est remplacée par une clé d'assertion dont la valeur est votre JWT encodée en base 64 selon la norme. Le client_id et le client_secret sont différents et fournis par DevAlto.

    Disons que l'url de votre LogAlto est https://acme.logalto.com , et que vous voulez vous authentifier avec votre JWT signé, vous feriez cette requête :

REST:

POST https://acme.logalto.com/api/oauth/v2/token
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=__base 64 encoded JWT__&client_id=__provided by DevAlto__&client_secret=__provided by DevAlto__

Curl:

curl 'https://acme.logalto.com/api/oauth/v2/token' -H 'Content-Type: application/x-www-form-urlencoded' --data 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=__base 64 encoded JWT__&client_id=__provided by DevAlto__&client_secret=__provided by DevAlto__'

Pour plus de clarté, les paramètres décodés ci-dessus sont les suivants :

grant_type: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion: __base 64 encoded JWT__
client_id: __provided by DevAlto__
client_secret: __provided by DevAlto__