Authentication guide
Introduction
Access to the LawVu Developer API is authenticated using the OAuth 2.0 authorization code flow along with with the use of an API subscription key on each request.
Authentication steps
The following steps can be used to issue, use and refresh authentication tokens:
Getting an auth code
The authorization code flow begins with the client directing the user to the authorize endpoint:
GET https://{web_host}/#/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}
Sample - constructing URL for signing in and retrieving auth code
Once the user is redirected to the Sign in link, they will see a login screen (will be authenticated via SSO) followed by a standard consent screen:
Note: Subsequent calls to the API will be made under the security context of this user account, therefore the users’ access level/permissions will need to be considered in the context of the integration workflows.
Getting an access and refresh token
At this point, the redirect URI specified in the previous section is called, along with a short-lived "code" query parameter (also known as the auth code).
This auth code can be redeemed for access and refresh token pair using the token endpoint.
The resulting access token can be used to perform an authenticated API call, and the refresh token can be used to refresh tokens.
POST https://{api_host}/account-apis/v1/auth/token
Sample - exchanging auth code for access and refresh tokens
The resulting access token can be used to perform an authenticated API call, and the refresh token can be used to refresh tokens.
Performing an authenticated API call
All calls to API endpoints must be authenticated using an access token.
To do this, the access token retrieved from the previous section must be provided as a “bearer token” in the Authorization HTTP header.
Note: you will also need to supply an API Subscription Key in the header of each request to API endpoints.
Sample - performing an authenticated API call
Refreshing tokens
Token rotation is defined by the OAuth V2 RFC spec.
Instead of having a permanent access token to make authenticated calls to LawVu, the access token expires. One benefit is that if an access token is stolen, it will only be valid for a relatively short time frame. A refresh token provides a means of refreshing your access tokens without having to ask your users to re-authenticate each time their access token is expired.
The token’s expiration time can be found by looking at the expires_in or expires properties returned along with the access token.
To get a fresh access token, you can exchange an existing refresh token for new access and refresh tokens.
POST https://{api_host}/account-apis/v1/auth/token
Note: refresh tokens eventually expire as well. If you receive an HTTP 400 Bad Request response from LawVu when trying to refresh a token, this means the user has been idle for too long. This means the user will have to authenticate to LawVu once again. Consider redirecting the user to the start of the process (per the Getting an Auth Code section).
Sample - refreshing tokens
Decoding access tokens
The access tokens returned by the LawVu API are Base64-encoded JSON Web Tokens (JWT).
Once decoded, you can pull useful information from the "claims" stored within such as the authenticated user's ID, name, permissions and Organization ID.
In the following sample, we demonstrate the retrieval of the authenticated user's Organization ID using the jwt-decode library:
Sample - decoding an access token
API Subscription Key
As an additional layer of security, all calls to the LawVu API must be secured using an API Subscription Key, supplied by LawVu to permit access to the API gateway.
Consumers of the API need to supply a valid subscription key via the Ocp-Apim-Subscription-Key request header when calling endpoints.
Sample - supplying API Subscription Key header