Managing your API subscriptions

To manage your API subscriptions, simply:

  1. Sign in with your GOV.UK One Login account.
  2. Select the My subscriptions tab within the top navigation menu on the Homepage. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:
  • API (API name)
  • Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
  • Manage Subscription link
  1. Select the Manage subscriptions link. This will show you the API Subscriptions page with the following:
  • Create subscription link
  • View API definition link to view API definition details including any uploaded files.
  • Environment
  • Status (Active or Inactive)
  • API Subscription name (given by at the time of creation)
  • View link to view an API subscription details
  • Delete link to delete an API subscription.

Subscribing to an API

You can subscribe to an API within a specified environment by following these steps:

  1. Find the API you wish to subscribe to by following the steps detailed in the Finding an API section of this guide.
  2. Select the API name. This will show you the API Overview page with details of the API.
  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 textbox to help you identify and differentiate it from others you might create. This is because 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 textbox. This describes why you require the API subscription.
  6. Select the Create subscription button to submit the subscription request. Or the 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 a message to tell you that. And upon submission, your subscription request will be reviewed by the API provider and the relevant permission granted. In the case where approval is not required to subscribe to an API environment, a justification will still have to be provided (for record purposes only) and the subscription will be created immediately.

Viewing API subscriptions

You can view your API subscriptions by following these steps:

  1. Select the My subscriptions tab within the top navigation menu on the Homepage. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:
  • API (API name)
  • Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
  • Manage Subscription link

Viewing an API definition

You can view an API definition by following these steps:

  1. Select the My subscriptions tab within the top navigation menu on the Homepage. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:
  • API (API name)
  • Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
  • Manage Subscription link
  1. Select the Manage subscriptions link. This will show you the API subscriptions page.
  2. Select the View API definition link. This will show you the API definition including overview, documents, environments, operations, release information and more.

Changing the name of an API subscription

You can change your subscription name by following these steps:

  1. Select the My subscriptions tab within the top navigation menu on the Homepage. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:
  • API (API name)
  • Subscriptions statistics including the number of subscriptions and status (Active or Inactive)
  • Manage Subscription link
  1. Select the Manage subscriptions link. This will show you the API subscriptions page.
  2. Select the Change link next to the subscription name. This will show you the Change subscription name page.
  3. Enter a new name for the subscription in the New display name textbox provided.
  4. Select the Change name button to submit.

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

Deleting an API subscription

  1. Select the My subscriptions tab within the top navigation menu on the Homepage. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:
  • API (API name)
  • Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
  • Manage Subscription link
  1. Select the Manage subscriptions link. This will show you the API subscriptions page.
  2. Select the Delete link located to the right of the subscription name for the relevant API environment. This will show you the Delete API subscription page with details including:
  • API name
  • API version
  • Environment
  • Subscription status.
  1. Select the Delete subscription button to delete that subscription. Or the Return to subscription link to cancel.

Alternatively:

  1. Select the My subscriptions tab within the top navigation menu on the Homepage. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:
  • API (API name)
  • Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
  • Manage Subscription link
  1. Select the Manage subscriptions link. This will show you the API subscriptions page.
  2. Select the View link next to the API subscription you wish to test. This will show you the API subscription detail page.
  3. Select the Delete link to the right of the Subscription details section of API details. This will show you the Delete API subscription page with details of the subscription you are about to delete including:
  • API name
  • API version
  • Environment
  • Subscription status.
  1. Select the Delete subscription button to delete that subscription. Or the Return to subscription link to cancel.

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 keys 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

  1. Select the My subscriptions tab within the top navigation menu on the Homepage. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:
  • API (API name)
  • Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
  • Manage Subscription link
  1. Select the Manage subscriptions link. This will show you the API subscriptions page.
  2. Select the View link next to the API subscription you wish to test. This will show you the API subscription detail page.
  3. Select the Disable link next to the Subscription details section of API details. This will show you the Disable API subscription page.
  4. Select the Disable subscription button to disable the subscription. Or the Return to subscription link to cancel.

Once a subscription is disabled, any existing integrations using the subscription will stop functioning immediately. And 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.

Testing an API subscription

You can test your API subscription by following these steps:

  1. Select the My subscriptions tab within the top navigation menu on the Homepage. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:
  • API (API name)
  • Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
  • Manage Subscription link
  1. Select the Manage subscriptions link. This will show you the API subscriptions page.
  2. Select the View link next to the API subscription you wish to test. This will show you the API subscription detail page.
  3. Select the Test API link next to the Subscription details section of API details. This will show you the API Test suite page with options such as:
  • Operation endpoint selection dropdown option
  • Add subscription key checkbox option
  • Add OAuth token checkbox option
  • Send button
  • Request URL textbox
  • Querystring parameter tab with Key and Value entry textboxes
  • Response body tab
  1. Select the endpoint for the API operation you want to test from the operation endpoint dropdown list (/Download/, /Echo-Get, /Echo-Post, /List, or /Upload). This will auto-fill the Request URL textbox.
  2. Select the Add subscription key checkbox option if you want to add a subscription key to the request.
  3. Select the Add OAuth token checkbox option, if you want to add OAuth token to the request.
  4. Enter the Key and corresponding Value text, if required for the selected operation endpoint.
  5. Select the Send button to make the request.

Viewing your API subscription keys

To view your API subscription Primary or Secondary key:

  1. Select the My subscriptions tab within the top navigation menu on the Homepage. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:
  • API (API name)
  • Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
  • Manage Subscription link

Regenerating your API subscription keys

To regenerate your API subscription Primary or Secondary key:

  1. Select the My subscriptions tab within the top navigation menu on the Homepage. This will show you the My subscriptions page with a list of all your subscriptions including detail such as:
  • API (API name)
  • Subscriptions statistics (including the number of subscriptions and status (Active or Inactive)
  • Manage Subscription link
  1. Select the Manage subscriptions link. This will show you the API subscriptions page.
  2. Select the View link next to the API subscription you wish to test. This will show you the API subscription detail page.
  3. Go to the Subscription key section of the API subscription detail page.
  4. Select the Regenerate link to the right of the key shown as masked text 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'. This will regenerate your new key with a Copy link to enable you to copy it accurately.

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 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 key and Secondary key at anytime.