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.


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.

When moving to the live environment you will need to change the host from test.eservices.ros.gov.uk to www.eservices.ros.gov.uk, and use live credentials.

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.


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).

URL

You might find it easier to follow the redirects in this step in a new window, by clicking the link.

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.

Copy and paste the code from the previous step here to continue.

URL

POST [[ getTokenURL() ]]

Headers

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

Body

[[ getTokenBody() ]]

Response

An access token was retrieved
[[ tokenResponse ]]

Response

[[ tokenError.status ]] [[ tokenError.statusText ]]
[[ tokenError.responseText ]]

Use the access token

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

You will need to contact the authentication server, as per the get token step, to get an access token.

URL

GET http://example.com/api/

Headers

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.

You will need to contact the authentication server, as per the get token step, to get a refresh token.

URL

POST [[ getTokenURL() ]]

Headers

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

Body

[[ getTokenRefreshBody() ]]

Response

An access token was refreshed
[[ tokenRefreshResponse ]]

Response

[[ tokenRefreshError.status ]] [[ tokenRefreshError.statusText ]]
[[ tokenRefreshError.responseText ]]

Is there anything wrong with this page?