Obtaining API Tokens via OAuth 2.0

This guide describes how to obtain authorization tokens for the LockitNetwork API via OAuth 2.0.

Quick Start

For API users already familiar with the OAuth 2.0 authorization framework, the following key data should get you started:

• Grant Type: Authorization Code
• Authorization Endpoint URI: https://api.lockitnetwork.com/oauth/authorize
• Token Endpoint URI: https://api.lockitnetwork.com/oauth/access-token
• Client authentication in token requests via HTTP basic access authentication
• PKCE is supported and recommended but not required.
• Access token scopes are not supported, yet.

Client Registration

If you are interested in registering as an OAuth 2.0 client, please contact support@lockitnetwork.com.

Authorization Example (without PKCE)

This example assumes a valid client registration with the following details:

• Client ID: example-client
• Client Secret: top-secret
• Redirect Endpoint URI: https://example-client.com/auth_code

Step 1: Authorization Request/Callback

We construct a URL based on the authorization endpoint URI and our client details:

https://api.lockitnetwork.com/oauth/authorize?response_type=code&client_id=example-client&state=example-state&redirect_uri=https%3A%2F%2Fexample-client.com%2Fauth_code

The state parameter is chosen by the client and should be used to maintain state between authorization request and callback.

The client typically instructs the user ("resource owner") to open the previously constructed URL in a browser. The user is then redirected to the LockitNetwork Tools page where they log in and grant (or deny) the client access to their data. Afterwards, the user is redirected to the client's redirect endpoint URI with additional parameters:

https://example-client.com/auth_code?code=example-auth-code&state=example-state

The code parameter contains our auth code while the state parameter refers to the one provided in the authorization request.

Step 2: Access Token Request/Response

Having successfully obtained our auth code, we can use it to request an access token. For this purpose, we have to issue an authorized POST request to the token endpoint URI with the necessary parameters in the request body (in application/x-www-form-urlencoded format). Since client authentication is required for this request, we have to add an Authorization HTTP header to our request. The username is the client ID and the password is the client secret. In our example the correct header would look like this:

Authorization: Basic ZXhhbXBsZS1jbGllbnQ6dG9wc2VjcmV0

The constructed request body reads like this:

grant_type=authorization_code&code=example-auth-code&redirect_uri=https%3A%2F%2Fexample-client.com%2Fauth_code

A corresponding curl command would read as:

curl -i \
-u 'example-client:top-secret' \
-d 'grant_type=authorization_code' \
-d 'code=example-auth-code' \
-d 'redirect_uri=https://example-client.com/auth_code' \
https://api.lockitnetwork.com/oauth/access-token

After issuing a correct POST request the response contains a JSON body containing our example access token:

{
  "access_token": "example-access-token",
  "refresh_token": "example-refresh-token",
  "token_type": "Bearer",
  "expires_in": 604800
}

Step 3: Make Authorized Requests to the LockitNetwork API

With a valid access token, we can call protected LockitNetwork API endpoints by providing a corresponding Authorization HTTP header. In our example the header would look like this:

Authorization: Bearer example-access-token

Step 4: Refresh Token Request/Response

After the access token is expired the client is able to obtain a fresh one using a refresh token. Like with the access token request, client authentication is required via HTTP basic access using an Authorization HTTP header. The token refresh request is sent as a POST request to the token endpoint URI with the following example request body:

grant_type=refresh_token&refresh_token=example-refresh-token

The response format is the same as for the access token response.