View the Project on GitHub COG-UK/docs

Updated 2020-09-11 by @samstudio8

Creating an OAuth application

Registering an OAuth application (e.g. your copy of Ocarina) with Majora

If you want an applicaton to perform actions as a Majora account holder, you need to register an application. Note that the testing and real versions of Majora are entirely separate, and so are the OAuth systems. The locations to register an application are:

Click “New application” and fill out the form as appropriate:

Finally, if your application has a web-based front end, you can specify a callback for authorised requests to automatically flow to - along with a grant token. In almost all cases, you will not need to provide your own Redirect Uris callback and should use the one we provide below.

As per NHS digital guidelines, we only allow applications that use the authorization code flow.

If you are following setting up ocarina go back to that document at this point.


Once you have an application, the authorisation flow can be summarised as follows:

1. Ask for a user to give permissions to your application (e.g. your copy of Ocarina)

2. Convert the new grant token to an access token

3. Receive an access token

4. Use the access token

You will need to send a Authorization header formatted: Bearer TOKEN where TOKEN is your access_token. All API endpoints in the v2 API support OAuth and rotating API keys.

API requests must continue to include the username and token in the request data, though these are not checked (this is just a feature that enables backward compatibility).

5. Refresh the access token

If successful, you’ll see the same JSON struct as step 3. Store the new access token and refresh token to repeat. You can automate this process easily through cron to keep your token rotated.


You must request at least one scope from a user. Every scope maps to a user permission in Majora. A user can only authorize an application if they have been granted all the permissions for all scopes requested. When specifying scope in Step 1, scopes must be separated by an URL-encoded space (%20).

Currently, OAuth scopes only cover the functionality provided by the uploader tool (e.g. biosamples and their collections, sequencing libraries and their pooling events and seqencing runs). To simplify matters during this trial phase, just request all scopes to cover these activities:


These will change and be expanded as we continue to integrate OAuth to the rest of the system.

More information

Common pitfalls

Published 2020-09-11. Updated 2020-09-11. Page maintainer @samstudio8.