# Authentication

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.

## **Types of authentication**

There are three options for authenticating your API requests:

<details>

<summary>OAuth2</summary>

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 <accessToken>`.

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.

</details>

<details>

<summary>HTTP Header</summary>

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.

</details>

<details>

<summary>HTTP Query Parameter</summary>

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.

</details>

## **Best practices**

* Keep your API keys and tokens secure at all times.
* Rotate your keys periodically to minimize the risk of unauthorised access.

## **Monitoring and alerts**

* Regularly check the usage patterns of your API keys.
* Set up alerts for unusual or unauthorised activities that could indicate a security breach.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.os.uk/os-apis/core-concepts/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.