> For the complete documentation index, see [llms.txt](https://docs.os.uk/os-apis/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.os.uk/os-apis/core-concepts/authentication.md). # Authentication This page outlines how to handle OS API authentication and recommends best practices for securing your OS API credentials. To use OS APIs you need to authenticate your requests. Before you can authenticate requests you need to add the API into an API Project in the OS Data Hub; this gives you access to a Project API Key and Project API Secret. See [Getting started with an API project](/os-apis/core-concepts/getting-started-with-an-api-project.md) for more information on setting up your API Project. Your API key, API secret and OAuth tokens provide access to your OS API project. Treat them like passwords and do not expose them in public websites, applications or source code. {% hint style="danger" %} ## OS API Service Terms The [OS API Service Terms](https://osdatahub.os.uk/support/legal/api-terms) require users to use “adequate technological and security measures to ensure that all access and use of any API Service is secure from unauthorised use or access.” This applies to both Open and Premium APIs available in the Data Hub. The guidelines on this page detail how to adequately secure your credentials and prescribe best practices for accessing the OS APIs. {% endhint %} ## **Types of authentication** There are three options for authenticating your API requests. Choose the method that best suits your application and its security requirements. Whichever method you use, you are responsible for protecting the credentials associated with your project.
OAuth2 Using OAuth 2 for authentication is a two-stage process. First you use the Project API Key and Secret to create an access token, and then you include the access token in an Authorization header on your API request. The value of the Authorization header should be 'Bearer', a space, and then the access token, e.g. `Bearer `. See the [OAuth 2 API](/os-apis/accessing-os-apis/oauth-2-api.md) documentation for detailed instructions on how to create an access token.
HTTP Header You can choose to authenticate your API request using a HTTP header. The header name should be `key`, and the value should be the Project API Key.
HTTP Query Parameter You can choose to authenticate your API request using a HTTP query parameter. The parameter name should be `key`, and the value should be the Project API Key.
## **Keep your credentials secure** If credentials are exposed, someone else may be able to use your API allowance, access licensed data through your application or generate unexpected usage against your account. #### Store credentials securely Store API keys, secrets and tokens in a secure credential store, for example: * Azure Key Vault * AWS Secrets Manager * Google Secret Manager * Environment variables or secret settings managed by your hosting platform Do not place credentials in publicly accessible configuration files. #### Do not put credentials in client-side code Do not embed API keys, API secrets or long-lived tokens in JavaScript, HTML or other code accessed by a user’s browser. A user can inspect the code and network requests and may be able to copy the credential. For more detail on securing credentials, please refer to our [OS Labs guidance](https://labs.os.uk/public/os-api-resources/articles/api-authentication). #### Do not commit credentials to source control Do not commit credentials to Git, GitHub, GitLab, Bitbucket or shared code archives. Use your repository or deployment platform’s secret-management features, and configure .gitignore rules where appropriate. #### Use least privilege Give each application no more access than it needs. Where practical: * Use separate API projects or credentials for different applications and environments. * Only add the APIs the application needs to the relevant API project. * Do not share the same credentials across unrelated services. * Remove or rotate credentials that are no longer required. #### Rotate credentials Replace credentials periodically, or immediately if you believe they may have been exposed. Update the application and revoke the old credentials as soon as the replacement is working. Users can regenerate the API key within each API project in the Data Hub. ## Recommended approach: use a backend proxy The most secure approach is to keep your OS API credentials on a server that you control. A backend proxy is a small service that sits between your users and OS APIs. ``` User browser or mobile application -> Your backend service -> Data Hub API ``` The browser or mobile app calls your backend service. This service then adds the OS API credential and sends the request to the OS API, returning only the response your application needs. Adopting this approach means: * Credentials remain on your server and are not sent to the user. * You can validate requests before forwarding them. * You can restrict which OS API endpoints and parameters your application uses. * You can apply monitoring, rate limits and other controls to your own service. {% hint style="info" %} ### When might I not need a backend service? You may not need a backend service or proxy for internal prototypes, proof-of-concepts, development tools, or applications that are not publicly accessible. In these cases, the risk of exposing a credential or unauthorised access to data is typically lower. {% endhint %} We recognise that not every user has the technical capability to build and operate a backend service immediately. If you choose to call an OS API directly from browser-based code in the short term, you should understand that the credential may be visible and reusable by others. To reduce the risk of calling the OS API directly from the browser: * Use short-lived OAuth tokens where the API and application pattern support them. * Apply any available restrictions, quotas and rate limits. * Use separate credentials for prototypes and production services. * Monitor usage for unexpected activity. * Rotate your API key regularly and after any suspected exposure. * Move to a backend architecture before the service handles sensitive, licensed or business-critical use cases. ## Monitor your usage Review usage within your OS Data Hub project and investigate activity that does not match the expected behaviour of your application such as unexpected increases in requests or consumption. If you think a credential has been exposed: * Stop using or revoke the affected credential. * Create a replacement credential. * Update your secure server configuration. * Review logs and usage to understand the possible impact. * Check source repositories, build output and deployed client-side code for other exposed credentials. ## Choose the right approach
ScenarioRecommended approach
Public interactive web map Use a backend proxy service. Do not embed OS credentials in client-side JavaScript.
Address search or lookup form Send the search request to your backend, which calls the relevant OS API.
Mobile application Use a backend proxy service. Do not depend on hiding credentials inside the app.
Server-to-server integration Store credentials securely on the server and use the authentication method supported by the API.
Short-lived prototype Prefer a backend service. If you accept the risk of a frontend implementation, use separate credentials, monitor usage and remove them when the prototype ends.
{% hint style="warning" %} ## Common Mistakes to Avoid * Embedding API secrets in JavaScript, HTML or mobile app code. * Publishing credentials in source-code repositories. * Creating an unrestricted open proxy. * Sharing one credential across unrelated applications. * Logging credentials in request URLs, application logs or error messages. * Assuming CORS or a domain restriction makes a client-side credential secret. * Leaving unused credentials active indefinitely. {% endhint %} {% hint style="success" %} ## Implementation Checklist * Credentials are stored in a server-side secret store or secure configuration. * No credentials appear in client-side code or public repositories. * The backend only permits required OS API operations. * Inputs are validated and errors do not reveal credentials. * Development and production credentials are separate. * Usage is monitored and credentials can be rotated quickly. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.os.uk/os-apis/core-concepts/authentication.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.