OAuth 2.0

Our products make use of an OAuth 2.0 base authentication server. Full details of the OAuth 2.0 spec are outside the scope of this document, but we will give a brief overview of some of the critical concepts.

How is authentication used?

On the whole when accessing a service that we provide that requires authentication you will be acting in one of two ways:

The second is the more complex, and usual situation, which we will discuss here.

Acting on behalf of a user

When accessing one of our APIs you will often be accessing data, or performing actions as a user, or for them. This is a common situation on the web; for example if you use a social media account to log into another service and allow that service to read some of your details.

As a provider of that 3rd party service, you are said to be a "client" accessing a "resource" owned by a "user-agent".

For the process to continue we need to be sure of a few things:

How this works in practice

You can follow the interactive Authentication tutorial to try this in a browser right now.

Access tokens expire, but can be refreshed

The access token you are given has a fixed life span. When it expires you will need to start the authentication process again.

To prevent you from having to ask the user to login again, when you are provided with a "refresh token" along with the access token. You can use the refresh token any time before the access token expires to get a new access and refresh token pair.

What happens when things go wrong?

The process is designed to stop if any thing is wrong at any point. Here are a few situations that can occur in the flow:

When getting an auth code

Situation HTTP response Outcome
Registers of Scotland determines you are not allowed to access the resource 302 - Redirect ?error=invalid_scope
The user doesn't log in n/a No feedback
The user doesn't have the ability to grant access 302 - Redirect ?error=insufficient_permissions
The user denies you access 302 - Redirect ?error=access_denied

When using an access token

Situation HTTP response
The user revokes permission they previously granted on a resource 401 - Unauthorised
Your access token expires 401 - Unauthorised

Note: You must code expecting that the authorisation workflow will fail. You should expect any call to our services to potentially return a "401 - Unauthorised" response.

To aid you testing these scenarios, we provide users who do not have the correct priviledges to grant access. Most other situations can be simulated yourself, by failing to login, or refusing to grant access.

Is there anything wrong with this page?