To explore and use an API, simply:

  1. Sign in with your GOV.UK One Login account here (as detailed in the Creating an account) section.
  2. Find the API you wish to use (as detailed in the Finding an API) section.
  3. Click on the name of the API you wish to use from the search result. This takes you to the API's detail page. The information on this page is grouped into sections which will depend on the API and the details entered by the API provider:

  • Header - Located at the top of the page with details including:

    • API Name
    • API description
    • API Version
    • Release version
    • API type

  • Overview - Gives a summary of purpose of the API.

  • Documents - Gives you information relating to technical documents supplied by the API provider including:

    • Data structure information
    • Uploaded schema (JSON Format)

  • Environments - Gives you information relating to available environments for the API including:

    • Environment (Dev, Staging or Live)
    • Base URL
    • Action (View or Subscribe)

  • Operations - Gives you information relating to available environments for the API including:

    • Operation Method (GET, POST)
    • Description
    • URL template

If you are already subscribed to an API, the action link within the Environments section will be 'View' so you can view any subscriptions. Else it will be 'Subscribe', so you can subscribe to API.

Click on the 'View' action link to go to the API subscriptions page with options to subscribe or view the list of subscription to an API environment.

Click on the 'Subscribe' action link to take you to the API environment subscription page. If you are not already subscribed, then follow the instructions in the Subscribing to an API section.

You can view your subscriptions at anytime by selecting the 'My subscriptions' tab within the top navigation menu on the Home page.

Subscribing to an API

You can create a subscription to an API and associated environment by following these steps:

  1. Find the API you wish to use for your application as detailed in Finding an API.
  2. Select the API name. This takes you to the API's Overview and details page.
  3. Select the Subscribe link next to the relevant environment (Dev, Staging, or Live) within the Environments section.
  4. Enter a name for the subscription in the 'Subscription name' box. This will help you identify and differentiate that subscription from others you might create as you can have multiple subscriptions for the same API to different environments or multiple subscriptions for the same API to the same environment.
  5. Enter a justification for your subscription in the 'justification for usage' box. This describes why you require the API subscription.
  6. Select the Create subscription button to submit the subscription request. Or Return to API link to cancel and return to the API Overview page.

If your chosen API environment requires subscription approval before it is activated, there will be message to tell you that. Upon submission, your subscription request will be reviewed by the API provider and permission granted. And in the case where approval is not required for an API environment, a justification will still be required (only for record purposes) and the subscription will be created immediately.

Managing your subscriptions

To manage your subscriptions, simply:

  1. Sign in with your GOV.UK One Login account here (as detailed in the Creating an account section.
  2. Select the 'My subscriptions' tab within the top navigation menu on the Home page. This takes you to the subscriptions page with a list of all your subscriptions including detail such as:
  • Environment
  • Subscription name (given by you at the time of creation)
  • Status (Active or Inactive)
  • Link to view API definition
  • Link to create subscription
  • Link to view a subscription
  • Link to delete a subscription

Selecting the 'Create subscription' link takes you to the Subscription creation page where you can create a new API subscription.

Selecting the 'View' link takes you to the API Subscription details page where you can view detail relating to that API subscription.

API subscription details page

This page contains detailed information about an API subscription, grouped into clearly defined sections:

  • Subscriptions details
  • Subscription key
  • Native OAuth Application-flow

Subscriptions details

This contains general details about an API subscription including:

  • Subscription name - given by user
  • Status
  • Created date
  • API name
  • API version
  • Environment
  • Base URL - URL to the API location.

Additionally, within this section of the subscription details page, you will find:

  • a Delete link to delete a subscription.
  • a Disable link to disable your API subscription.
  • a Change link to change the name of your subscription.

Changing the name of an API subscription

Selecting the Change Link takes you to the Change subscription name page. From this page you can make changes to your subscription name by following these steps:

  1. Enter a new name for the subscription in the New display name box provided.
  2. Select the Change name button to submit.

The change to the Subscription name will be reflected immediately. However, the status will show 'Update in progress' until the change has fully updated through the system at which point the status changes to 'Active'.

Once a subscription is disabled, any existing integrations using that subscription will stop functioning immediately.

Selecting the API name takes you to the API technical details page.

Selecting the Base URL link takes you to the base location of the subscription API.

Deleting an API subscription

Selecting the Delete link takes you to the Subscription deletion page with details including:

  • API name
  • API version
  • Environment
  • Subscription status.

The Delete subscription button allows you to delete that subscription. And the Return to subscription link to return to the subscription details page.

Once the subscription is deleted, any existing integrations using the subscription will be denied access immediately. You will also lose both the Primary and Secondary key associated with that subscription and the OAuth Client ID relating to for Native OAuth Application-flow. This cannot be reversed, so make sure you want to delete the subscription.

Disabling an API subscription

Selecting the Disable link takes you to the Disable API subscription page with details including:

  • API name
  • API version
  • Environment
  • Subscription status

The Disable subscription button allows you to disable that subscription. And the Return to subscription link to return to the subscription details page.

Once a subscription is disabled, any existing integrations using the subscription will stop functioning immediately.

Subscription key

This section contains details about API subscription key including:

  • Instructions - given by the provider on how to use the subscription key
  • Header name
  • Query parameter name
  • Primary key
  • Secondary key

Below each subscription key is a last generation timestamp to indicate when the current key was generated.

Within this section of the subscription details page, you will find:

  • a View link to view your API subscription's primary key.
  • a Regenerate link to generate a new primary key. This can be for a number of reasons including a key being compromised or you simply just want a new key.
  • a View link to view your API subscription's secondary key.
  • a Regenerate link to generate a new secondary key. This can be for a number of reasons including a key being compromised or you simply just want a new key.

Primary key is your unique default key used to authenticate your request and grant you access to consume an API.

  • Select the View link to view your subscription's primary key. Or the Regenerate link to generate a new key.

Secondary key is your unique alternative key which can be used in the absence or failure of a primary key to authenticate your request and grant you access to consume an API.

  • Select the View link to view your subscription's primary key. Or the Regenerate link to generate a new key.

It is worth noting that once you regenerate a subscription key, any API subscription using that key will stop functioning immediately. This is one of the reasons for having a Secondary subscription key which can be a substitute for the Primary key before generating a new Primary key for a interruption free operation. You can rotate between the Primary and Secondary keys at anytime.

Native OAuth Application-flow

This section contains detail about API subscription key and the process of obtaining a token for a naitive applications including:

  • Instructions
  • OAuth token endpoint - This is additional information that needs to be provided as part of the request relating to the endpoint. An example is provided in the Testing an API page using Postman.
  • OAuth Client ID - This is an unique client identifier. And it cannot be changed.
  • Primary key
  • Secondary key
  • OAuth Scope - This is additional information that needs to be provided relating to the endpoint. An example is provided below on how to do this using Postman.

Below each Native OAuth subscription key is a last generation timestamp to indicate when the current key was generated.

Within this Native OAuth Application-flow section of the subscription details page, you will find:

  • a View link to view your API subscription's primary key.
  • a Regenerate link to generate a new primary key.
  • a View link to view your API subscription's secondary key.
  • a Regenerate link to generate a new secondary key.

Primary key is your unique default key used to authenticate your request and grant you access to consume an API.

  • Select the View link to view your subscription's primary key. Or the Regenerate link to generate a new key.

Secondary key is your unique alternative key which can be used in the absence or failure of a primary key to authenticate your request and grant you access to consume an API.

  • Select the View link to view your subscription's primary key. Or the Regenerate link to generate a new key.

Once you regenerate a subscription key, any API subscription using that key will stop functioning immediately. This is one of the reasons for having a Secondary subscription key which can be swapped in the place of the Primary key before generating a new Primary key for a interruption free operation. You can rotate between the Primary and Secondary keys are anytime.

Additionally, when a subscription is disabled the keys remain within the API subscription details and do not changed. This means all keys remain valid, however any API subscription using that subscription key will stop working. Once, the subscription is re-enabled, it will start working again with those keys within 5 seconds.