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
• Revocation Endpoint URI (RFC 7009): https://api.lockitnetwork.com/oauth/revoke
• Client authentication in token requests via HTTP basic access authentication
• Only confidential clients are supported: every token and revocation request authenticates with the client secret.
• PKCE is supported and recommended but not required.
• Access token scopes are not supported, yet.
• Authorization codes are valid for 10 minutes and can be exchanged once.

Client Registration

If you are interested in registering as an OAuth 2.0 client, please contact [email protected].

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.

The response contains a refresh token. Store it in place of the one you sent and use it for the next refresh: it may be a new one, and then the one you sent no longer works. The previous access token stops working as soon as the refresh succeeds.

An authorization ends when it has not been refreshed for a year after its access token expired, or when the user or your client revokes it. A refresh after that fails with invalid_grant; send the user through Step 1 again.

Step 5: Revoke an Authorization

When the user disconnects your integration or logs out, revoke the authorization with a POST request to the revocation endpoint URI. Authenticate like on the token endpoint and send either the refresh token or the access token:

curl -i \
-u 'example-client:top-secret' \
-d 'token=example-refresh-token' \
-d 'token_type_hint=refresh_token' \
https://api.lockitnetwork.com/oauth/revoke

The response is 200 OK with an empty body, also when the token is unknown or already revoked. Revoking either token revokes the whole authorization: both its access token and its refresh token stop working.