Documentation The Livelox public API Accessing the API through user delegation with OAuth2

Désolé, cette information n'est pas disponible en français. Elle reste affichée en: English.

Accessing the API through user delegation with OAuth2

For end-user applications that are accessing user-specific data, authorization to access the API should be given by the users rather than by using an API key. The OAuth2 protocol is used, applying the Authorization Code with PKCE Flow. This means that users will experience a one-time redirection to the Livelox website, where they allow your application to access Livelox on their behalf.

OAuth2 endpoints

Authorization endpoint: https://api.livelox.com/oauth2/authorize
Token endpoint: https://api.livelox.com/oauth2/token
Token revocation endpoint: https://api.livelox.com/oauth2/revoke
User info endpoint: https://api.livelox.com/oauth2/userinfo

Client ID

The OAuth2 protocol uses client_id as an identity for the calling application. We will assign a client_id to your application, typically the application's name.

Scopes

A scope is a mechanism in OAuth2 used to limit an application's access to a user's account. It defines exactly what actions an app can perform or what data it can access on the user's behalf. In Livelox, the following scopes are used:

events.import - lets the application import course setting information to Livelox events on behalf of a user
routes.import - lets the application import GPS routes to Livelox on behalf of a user

Token life lengths

Authorization codes are valid for 10 minutes. Access tokens are valid for 24 hours. Refresh tokens do not expire. Users can revoke tokens or change scopes in their Livelox account settings.

Typical workflow

The following steps show how your application interacts with Livelox to obtain a user's consent to perform an API request on the user's behalf. Your application must have that consent before it can execute a Livelox API request that requires user authorization.

Redirect to the Livelox consent page: https://api.livelox.com/oauth2/authorize?response_type=code&scope={scope}&redirect_uri={redirect_uri}&client_id={client_id}&state={state}&code_challenge={code_challenge}&code_challenge_method=S256.
- redirect_uri: address for redirecting back to your app so you can capture the authentication code. For mobile apps, use the custom URL scheme method: Android, iOS.
- state: specifies any string value that your application uses to maintain state between your authorization request and the authorization server's response. Read more here.
- code_challenge: BASE64URL-ENCODE(SHA256(ASCII(code_verifier))), where code_verifier is a key that your app sets and that you then send in step 4. Read more here.
If not already logged in, the user enters their Livelox username and password on the consent page. Then the user approves that the app can post data to Livelox.
The user is redirected to your app: {redirect_uri}?code={code}&state={state}
- redirect_uri: same as specified in step 1
- code: authentication code, used in step 4
- state: same as specified in step 1
Your app creates authentication keys through the Livelox API.

POST https://api.livelox.com/oauth2/token with www-form-urlencoded body grant_type=authorization_code&code={code}&client_id={client_id}&code_verifier={code_verifier}&scope={scope}.
- code: from step 3
- code_verifier: from step 1
The response contains access_token, refresh_token, expires_in, etc. Store these on your side.
As long as the access_token has not expired, use it in the Authorization HTTP header when calling the API.

Authorization: Bearer {access_token}
When an access_token has expired, the server responds with HTTP 403. Use refresh_token to create a new access_token.

POST https://api.livelox.com/oauth2/token with www-form-urlencoded body grant_type=refresh_token&client_id={client_id}&refresh_token={refresh_token}.
- refresh_token: from step 4