LogoLogo
OS Docs HomeOS NGDOS APIsOS Download ProductsMore than MapsOS Data Hub
  • Introduction to OS APIs
  • Core Concepts
    • Getting started with an API project
    • Authentication
    • Error codes
    • Rate-limiting policy
    • OS API branding
    • Service level agreements
    • Service availability dashboard
  • Accessing OS APIs
    • OS Maps API
      • Layers and styles
      • Getting started
        • ESRI ArcGIS Online
        • ESRI ArcGIS Pro
        • ESRI ArcMap
        • Cadcorp SIS
        • MapInfo Pro
        • QGIS
      • Technical specification
        • ZXY
        • WMTS
      • Code examples
    • OS Vector Tile API
      • What data is available?
      • Getting started
        • ESRI ArcGIS Pro
        • Cadcorp SIS
        • QGIS
        • Create a web application using the OS Vector Tile API
      • Technical specification
        • Service Metadata
        • Stylesheet
        • Tile request
      • Code examples
      • Stylesheets
    • OS NGD API – Tiles
    • OS NGD API – Features
    • OS Features API
      • OS Product Archive
      • What data is available?
      • Getting started
        • ArcGIS Online
        • ArcGIS Pro
        • ArcMap
        • Cadcorp SIS
        • MapInfo Pro
        • QGIS
      • Technical specification
        • getCapabilities
        • describeFeatureType
        • getFeature
        • Filtering
        • Paging
        • Empty values
      • Code examples
    • OS Names API
      • Getting started with example queries using Node.js
      • Technical specification
        • Find
        • Nearest
      • Code list
      • Code examples
    • OS Linked Identifiers API
      • What data is available?
      • Getting started with implementing a look-up application
      • Technical specification
        • Identifier
        • Identifier Types
        • Feature Types
        • Product Version Information
      • Code examples
    • OS Places API
      • Getting started with example queries using Node.js
      • Technical specification
        • Find
        • Postcode
        • UPRN
        • Nearest
        • BBOX
        • Radius
        • Polygon
      • Datasets
      • Code lists
      • Code examples
    • OS Match & Cleanse API
      • End of Life Information
      • Getting started with an example match query using Node.js
      • Technical specification
      • Datasets
      • Code lists
    • OS Downloads API
      • Getting started
        • Automating OS OpenData downloads
        • Automating OS Premium data downloads
      • Technical specification
        • OpenData products
        • OpenData product details
        • Download an OpenData product
        • OpenData product image
        • Data packages
        • Data package ID
        • Data package version
        • Data package version ID
        • Download a data package
    • OAuth 2 API
      • Getting started
      • Technical specification
  • Additional resources
    • OS API Wrappers
      • JavaScript
      • Python
      • R
  • Extra Links
    • Accessibility
    • Contact us
    • PSGA Product Summary
    • Terms and conditions
Powered by GitBook
On this page
  • What you need?
  • Instructions

Was this helpful?

  1. Accessing OS APIs
  2. OAuth 2 API

Getting started

PreviousOAuth 2 APINextTechnical specification

Last updated 4 months ago

Was this helpful?

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

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

Generate Access Token

  • Open a command line window (how you do this depends on your operating system).

  • 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.

  • Execute the command by pressing Enter.

  • 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.

2

Use Access Token

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"

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

overview documentation