Authentication tutorial

Overview

This document is an interactive guide to using the authentication system for API access. You can follow through this document and input your own credentials to try using authentication for real.

For background on Authentication and OAuth 2.0, please see the Authentication overview

We will be attempting to access a demo scope called api_demo. You may want to logout first to get the full experience, or jump straight to the login / grant scope step.

• Logout - start fresh
• Login / grant scope - login and grant a 3rd party access to your details
• Get an access token - confirm the access with the authentication server
• Use the access token - use the access
• Refresh the access token - extend the access when is about to expire

Environment

This tutorial uses our test environment. A demo client ID, secret and user account are provided below. See test environments for more details of this environment.

If you have already requested API access and received your test client ID, secret and user accounts, you can use these instead. You will need to enter the redirect URI you supplied in your application, and change the scope to api.lr.application.

Once you have completed testing and received your live API credentials, you can also try out the live environment with this page.

Logout

Before you start with authentication, you may want to ensure your user is logged out. Don't worry if the page that loads is blank, the important point is that you are presented with a login screen at the next step.

GET [[ getLogoutURL() ]]

Login / grant scope

After this your user will need to login to grant access to the scope. If the user is already logged in, they will just be presented with the prompt to access the scope. The scope you need will depend on the application you are trying to access.

If the login is successful, the redirect URL will be followed. This would typically be back to your app. Notice the ?code=... query string added to the end of the returned URI. This is the token you will need to exchange with the authentication server in the next step.

An optional state parameter is used to maintain state between the request and callback. This should be used for preventing cross-site request forgery as described in OAuth 2.0 specification (particulary sections 4.1.1 and 10.12).

GET [[ getLoginURL() ]]

Get an access token

The step above should have presented you with a successful redirect from the authentication server to your Redirect URI. But how do know that the redirect came from the authentication server and not a malicious user?

Your application will now need to check with the authentication server to prevent people from spoofing your Redirect URI by confirming the code. This will give you an access token, which you will use to access all further API resources.

POST [[ getTokenURL() ]]

Content-Type: application/json
Accept: application/json

[[ getTokenBody() ]]

[[ tokenResponse ]]

[[ tokenError.responseText ]]

Use the access token

You now have an access token you can use to access an API.

GET http://example.com/api/

Content-Type: application/json
Accept: application/json
Authorization: Bearer [[ accessToken ]]

Refresh the access token

At any time before the access token expires, you can refresh it, to get a new access and refresh token. This can happen in the background, without requiring input from your users.

You can perform this action as many times as you like, as long as the existing access token has not yet expired.

POST [[ getTokenURL() ]]

Content-Type: application/json
Accept: application/json

[[ getTokenRefreshBody() ]]

[[ tokenRefreshResponse ]]

[[ tokenRefreshError.responseText ]]