> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/api/authentication.md).

# Authentication and scopes

API keys, permission scopes and access to shared resources.

Every REST request uses an API key in an HTTP header:

```http
Authorization: Bearer kn_your_api_key
```

Create and manage keys in [Settings](https://portal.kinesis.network/dashboard/settings). A key's token is shown once. Keep it in a secret manager or environment variable, and send it over HTTPS. Browser sign-in cookies do not authenticate the public API.

API keys may have an expiry, a set of permission scopes and a list of allowed projects. Full access uses `*`, including scopes added later. A key can never grant more access to a resource than its user already has.

## Permission scopes

| Scope             | What it permits                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `projects:read`   | Read projects visible to the user                                                            |
| `projects:write`  | Create and rename projects, subject to ownership rules                                       |
| `projects:admin`  | Delete projects and manage project sharing                                                   |
| `apps:read`       | Read app configuration, status and builds                                                    |
| `apps:write`      | Create, update, start, stop, restart and rebuild apps                                        |
| `apps:admin`      | Delete or move apps and manage app sharing                                                   |
| `pools:read`      | Read grids and servers                                                                       |
| `pools:write`     | Manage grids, servers, provisioning, BYOD, Smart Lifecycle and SSH keys                      |
| `pools:admin`     | Delete grids and manage grid sharing                                                         |
| `monitoring:read` | Read app logs, usage metrics, build logs and server logs                                     |
| `vcs:read`        | Browse connected GitHub accounts and repositories                                            |
| `billing:read`    | Read balance, costs, invoices, charges, credits, payment methods and node protection         |
| `billing:write`   | Change auto-reload, payment methods and node protection; redeem vouchers and create payments |
| `account:read`    | Read notifications and received invitations                                                  |
| `account:write`   | Manage notifications, accept/decline invitations and leave shared resources                  |
| `compute:spend`   | Authorize operations that start, resize or provision compute                                 |

Within a family, `admin` includes `write` and `read`; `write` includes `read`. `compute:spend` is separate. Every operation's reference lists its exact requirements, including combinations of scopes and conditions that depend on the request.

{% hint style="info" %}
The scope name for grids is `pools`, even though the public resource is called a grid. For example, use `pools:read` when listing grids.
{% endhint %}

## Spending and ownership

Creating, starting and restarting apps require `compute:spend` as well as `apps:write`. App updates that change compute sizing, instance bounds, volumes or build source may require spending permission too. Server operations and billing requests have their own requirements; check the endpoint before granting access.

Scopes and resource roles are separate checks. For projects and apps, a viewer can read and an editor can perform the supported editing operations. Deletion, project renaming, grid targeting, repository-source changes and custom domains have ownership requirements. An `admin` scope does not turn a shared-resource editor into its owner.

## Sharing permissions

For sharing, the required admin scope follows `resourceType`: `project` uses `projects:admin`, `app` uses `apps:admin`, and `grid` uses `pools:admin`. Owners manage project/app sharing; grid editors can also manage grid sharing. Invitation cancellation checks the invitation's resource type at runtime. A scope does not confer ownership. See [Sharing](/api/sharing.md).

## Project restrictions

An empty `projectIds` list means the key is not pinned to specific projects. A nonempty list restricts project and app access to those projects. The list does not grant membership in a project.

A pinned key cannot create a project, because the new project would fall outside its restrictions. Use `GET /me` to inspect the key before running an integration.

## OAuth and MCP

OAuth access tokens are accepted by the MCP server only. They cannot be used with REST `/v1` endpoints. For MCP connections, see [Connect an MCP client](/mcp/connect.md).

## Authentication failures

| Response                     | Meaning                                             | Next step                                             |
| ---------------------------- | --------------------------------------------------- | ----------------------------------------------------- |
| `401 unauthorized`           | Missing, malformed, expired or revoked credential   | Check the bearer header and key                       |
| `403 insufficient_scope`     | A required permission is missing                    | Inspect `requiredScopes`                              |
| `403 key_project_restricted` | The key cannot access this project                  | Use a permitted project or adjust the key             |
| `403 forbidden`              | The user's resource role is insufficient            | Ask the owner to perform the action or adjust sharing |
| `403 account_frozen`         | The account cannot use this credential or operation | Contact support                                       |

Record the response's request ID when reporting a problem. Never include the API key in a support message.


---

# 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 dynamically by asking a question.

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

```
GET https://docs.kinesis.network/api/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.