Getting started

This guide shows you how to get started using the OAuth 2 API. It takes you through the process of:

• Generating an access token using the OAuth 2 API endpoint.

• Using the access token to access OS Data Hub APIs.

If you are not familiar with the OAuth 2 API please read the overview documentation before proceeding.

What you need?

• Basic knowledge of the command line.

• curl command line tool. Windows 10 (v1803) and later, and macOS, both come with a bundled curl tool

• A project in the OS Data Hub. See Getting started with an API project for more information.

Instructions

Generating and using an OAuth 2 access token

This example uses the OS Maps API and a curl command line tool.

The following instructions demonstrate how to generate an access token using the OAuth 2 API, and to then use that access token to access the OS Maps API.

1. Open a command line window. How you do this depends on your operating system.

2. Type or copy the following into the command line while substituting projectAPIKey and projectAPISecret with your project’s API key and secret:

   curl -u "projectAPIKey:projectAPISecret" -d "grant_type=client_credentials" "https://api.os.uk/oauth2/token/v1"

   Note your API Key and Secret should be surrounded by double quotes (") and separated by a colon (:). The above example uses the curl support for HTTP basic authentication to base-64 encode the Project API Key and Secret, and to set up the Authorization header. When using other HTTP clients or libraries you may need to use different options, or you may need to setup and encode the Authorization header manually.

3. Execute the command by pressing Enter.

4. The response should look similar to the following:

   {"access_token":"{accessToken}","expires_in":"{expiryPeriod}","issued_at":"{issuedTimestamp}","token_type":"Bearer"}

   • {accessToken} is the access token you need for requests to OS Data Hub APIs

   • {expiryPeriod} is the length in seconds until the access token expires.

   • issuedTimestamp} is the timestamp of when the access token was issued.

   If an access token is not generated, check that you have copied over the API Key and Secret correctly, and that they are surrounded by double quotes, and separated by a colon. You may also find it helpful to add the --verbose flag to the curl command while debugging the issue.

5. You can now use the access token to make API requests. Note that the access token is time limited, and will expire soon.

6. Type or copy the following into the command line while substituting {accessToken} with the access token returned in the previous step. Note that the value of the Authorization header is the word Bearer, then a space, and then the access token.

   curl -H "Authorization: Bearer {accessToken}" "https://api.os.uk/maps/raster/v1/wmts?service=wmts&request=getcapabilities"

7. If successful, this will return the GetCapabilities document for OS Maps API (WMTS).