# Authentication (/api/authentication)

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

Send the API key in the `Authorization` header of each request, with the `Bearer` scheme.

```bash
curl https://api.deepscout.ai/v1/projects \
  -H "Authorization: Bearer $SCOUT_API_KEY"
```

A request without a key gets `401` with the code `NOT_AUTHENTICATED`. A request with an unknown or revoked key gets `401` with the code `INVALID_API_KEY`.

<Callout title="Deprecated: the token parameter">
Older integrations send the key in a `token` header or in a `?token=` query parameter. Both still work, but they are deprecated. Use the `Authorization` header in new code.
</Callout>

## Key scopes [#key-scopes]

An API key always belongs to you, the user who created it. Its scope sets where the key works.

| Scope | Console label | Where the key works |
| --- | --- | --- |
| `USER` | All my projects | All endpoints, for all projects that you can access. |
| `PROJECT` | The name of one project | The project, website, job, sample, export and contact request endpoints, only for this project. |

Use a `PROJECT` key to keep an integration or an agent inside one project. With this key:

- [`GET /projects`](/api/reference/projects/list-projects.md) shows only the project of the key.
- A request for another project gets the same error as a project that you cannot access, for example `404 PROJECT_NOT_FOUND`.
- The account, customer and billing endpoints answer `403 INSUFFICIENT_SCOPE`. The key cannot create keys or projects, and it cannot read or top up the credit.
- The key has your role in the project. With the `ADMIN` or `EDITOR` role, it can approve jobs, and the jobs use the credit of the customer.

Use a `USER` key for a script that also manages keys, projects or the credit.

A request that needs `project_id` with a `USER` key also needs it with a `PROJECT` key. The export download, [`GET /exports/{dataset}`](/api/reference/exports/get-export.md), is the only exception. With a `PROJECT` key, it always uses the project of the key, and `project_id` is optional.

## Manage keys [#manage-keys]

You can manage keys in the console, under **Settings → API keys**, or with the API.

| Action | Request |
| --- | --- |
| List your active keys | [`GET /account/api-keys`](/api/reference/account/list-api-keys.md) |
| Create a key | [`POST /account/api-keys`](/api/reference/account/create-api-key.md) |
| Revoke a key | [`DELETE /account/api-keys/{key_id}`](/api/reference/account/revoke-api-key.md) |

The API shows the full key only one time, in the response to the create request. The list shows only the last four characters, in `key_suffix`.

```bash
curl https://api.deepscout.ai/v1/account/api-keys \
  -H "Authorization: Bearer $SCOUT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Data warehouse", "project_id": null}'
```

```json title="Response (201 Created)"
{
  "api_key": "Xb3v...full-key...9QaL",
  "key_id": "key_01k7c4m2n3p4q5r6s7t8v9w0x1",
  "scope": "USER"
}
```

Send `project_id: null` for a `USER` key, or the ID of a project for a `PROJECT` key.

<Callout type="warn">
After you revoke a key, the API can accept it for up to 5 more minutes. If a key leaks, revoke it and replace it immediately.
</Callout>

You can have more than one active key. To rotate a key without downtime, create the new key, change your integration to use it, and then revoke the old key.

## Roles [#roles]

What a key can do also depends on your roles. A key has the roles of the user who created it.

### Customer roles [#customer-roles]

A customer is the account that pays. Each user has a role in each customer: `OWNER`, `ADMIN` or `MEMBER`. [`GET /customers`](/api/reference/customers/list-customers.md) shows your role.

| Action | Needed role |
| --- | --- |
| Read the customer, its quotas and its billing | `OWNER` or `ADMIN` |
| Create a project | `OWNER` or `ADMIN` |
| Top up the credit | `OWNER` or `ADMIN` |

### Project roles [#project-roles]

Each user also has a role in each project: `ADMIN`, `EDITOR` or `VIEWER`. When you create a project, you become its `ADMIN`.

| Action | Needed role |
| --- | --- |
| Read websites, jobs, samples and exports | Any role |
| Create, approve and cancel jobs | `ADMIN` or `EDITOR` |
| Ask support about a failed job | `ADMIN` or `EDITOR` |
| Rename the project, change its localization, remove a website, remove a setup job | `ADMIN` |

A request without the needed role gets `403` with the code `INSUFFICIENT_ROLE` or `PROJECT_ACCESS_DENIED`. A project that you cannot access gets `404 PROJECT_NOT_FOUND`. Updating a project, removing a website and creating a project key answer `403 PROJECT_ACCESS_DENIED` instead.

<Callout title="Managed customers">
The self-service API shows only the projects of self-service customers. If DeepScout manages your account, use the [export files](/activation.md) of your projects.
</Callout>