# Authentication
URL: https://docs.awellhealth.com/api-reference/guides/authentication

> For the complete documentation index, see [llms.txt](https://docs.awellhealth.com/llms.txt).





Every request to the Orchestration API must be authenticated. This page explains how to obtain
a key and how to send it. It is the single source of truth for authentication; other pages
link here rather than repeating it.

## Obtain an API key [#obtain-an-api-key]

An administrator creates API keys in the CareOps portal — you don't need to ask Awell for one.

1. Open **Integrations** from the bottom of the left navigation.
2. Go to the **API keys** tab.
3. Click **Create API key**.

<img alt="The API keys tab of Integrations in the CareOps portal, listing existing keys by Name, Description, Created by and Created at, each with a delete button, and a Create API key button at the top right" src="__img0" />

**The key is shown once, when you create it.** Copy it straight into your secrets store — you
cannot retrieve it later, and the list above shows only its name and when it was created. If you
lose it, create a new key and delete the old one.

Keys are **per environment**, so a key created in Sandbox does not work against production. See
[Environments](/api-reference/guides/environments).

Keys do not expire, and there is no rotation schedule to keep up with.

## Send the key [#send-the-key]

Put the key in an `apiKey` header on every request. The value is the key itself — there is no
`Bearer` prefix and no other header to set. The endpoint you send it to is what selects the
environment, so nothing in the request names one.

```bash
curl https://api.sandbox.awellhealth.com/orchestration/m2m/graphql \
  -H 'Content-Type: application/json' \
  -H 'apiKey: YOUR_API_KEY' \
  -d '{"query": "query { patients(pagination: {count: 1, offset: 0}) { patients { id } } }"}'
```

### Send it from a backend, never a browser [#send-it-from-a-backend-never-a-browser]

The Orchestration API is a **machine-to-machine API**. A key authenticates as your whole tenant, so
anyone holding one can create patients, list every care flow, or start care flows on your behalf.

That rules out calling this API from front-end code. Anything in a browser or mobile app ships the
key to whoever is looking. Requests belong in a backend service that can hold the key without
exposing it.

## Keep keys safe [#keep-keys-safe]

* Give a key only to the people and services that need it.
* Keep keys out of source control. Store them in environment variables or a secrets manager.
* Replace a key if you suspect it has been exposed: create a new one, move your callers over, then
  delete the old one. There is no scheduled rotation, so this is the only time you need to.

## Related [#related]

* [Getting started](/api-reference/guides/getting-started)
* [Environments](/api-reference/guides/environments)