Integration and API

API documentation

The documentation for the available endpoints is located at https://api.deval.to/.

Authentication

To connect to the API, you need to authenticate a specific user whose password you know.

Let's say the LogAlto url is https://acme.logalto.com , and you want to authenticate bob@acme.com with the password Kj78qc , you would make this request:

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'

For clarity, the parameters decoded above are as follows:

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

The response to the authentication request is as follows:

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

Authorization

The access token returned in response to the above authentication request must then be used to authorize all subsequent API requests with a "Bearer header" like this:

REST:

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

Curl:

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

Refreshing your access token

As you can see from the response to the authentication request, the access token expires after 3600 seconds (1 hour). After that, you need to obtain a new access token to continue using the API. You can either re-authenticate or refresh your access token with the refresh_token command. In both cases, the requests and responses are similar, except that refreshing your token does not require to post your password. Here's what the request to refresh your token would look like, again using the same example:

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'

For clarity, the parameters decoded above are as follows:

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

The response to the authentication request is as follows:

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

As you can see, this returns a new access token as well as a new refresh token to continue using the API for another hour and so on.

Note that, although not specified in the answer, the refresh token also expires, but only after two weeks.

Authentication with JWT

This section assumes that you are already familiar with JSON Web Tokens.

Enabling JWT authentication

1. Generate an RSA key pair with the aes256 algorithm and a 4096 bits private key. Here is how you could do it on Linux with 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"
	

2. Send us your public key file and the email adresses of existing LogAlto users who should be authorized to authenticate with this key.
3. We will send you back the required information with which you can authenticate these users with a JWT.

Authenticating after enabling JWT authentication

1. Here is the JWT header and payload required for authenticating with LogAlto.
2. Header:

{
  "typ": "JWT",
  "alg": "RS256"
}
	

1. Payload:

{
  "jti": "__Version 4 UUID__",
  "exp": __expires at UNIX timestamp__,
  "iss": "__provided by DevAlto__",
  "sub": "__email of the user__",
  "aud": "__your LogAlto URL__"
}
	

• The jti claim must be a valid Version 4 UUID. You are responsible for generating it.
• For security reasons, the exp request must not be too far in the future. Note that the token expires as soon as it is used for authentication, regardless of the exp request.
• The iss claim is provided by DevAlto when we authorize your public key.
• The sub claim can be any authorized user email for your public key.
• The aud claim is LogAlto's URL.

1. Once you have your JWT signed with the above requirements, you can use it to authenticate yourself. The request is similar to what is documented above for a password, except that the password key is replaced by an assertion key whose value is your JWT encoded in base 64 according to the standard. The client_id and client_secret are different and supplied by DevAlto.

   Let's say your LogAlto url is https://acme.logalto.com , and you want to authenticate with your signed JWT, you would make this request:

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__'
	

For clarity, the parameters decoded above are as follows:

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__