> 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, organization selection, scopes and resource access.

REST requests use an API key in the HTTP header:

```http
Authorization: Bearer kn_your_api_key
```

Create and manage keys under **API keys** in [Account settings](https://portal.kinesis.network/dashboard/account). The token is shown once. Keep it in a secret manager and send it over HTTPS. Creating a key or changing its permissions may require your second factor; email/password accounts must enable two-factor authentication first. Browser sign-in cookies do not authenticate the public API.

## Whose permissions apply?

A key acts as its person in every organization they belong to, with their role in each. A Developer's key cannot administer infrastructure; a Viewer's key only reads. Scopes, organization limits, project limits and resource access all apply together. An `admin` scope never grants the Admin organization role.

Full access is `*`, including scopes added later and spending. Restricted keys carry explicit scopes, an optional expiry and a **Where it works** selection: all organizations, chosen organizations or specific projects. All-organizations keys include organizations the person joins later.

Use `GET /me` to inspect `apiKey.scopes`, `apiKey.projectIds` and top-level `limitedToOrgs`. `limitedToOrgs: null` means every organization the person belongs to; `GET /orgs` returns the organizations currently reachable and the person's role in each. An empty `projectIds` list means no project restriction; other restrictions still apply.

## Select an organization

Calls on a project, app or grid resolve the organization from the resource. Organization-level calls, such as creating a project or managing servers, billing or members, take the slug in `?org=`. It is a query parameter even for `POST` and `PATCH`.

```bash
curl --get https://api.kinesis.network/v1/members \
  -H "Authorization: Bearer $KINESIS_API_KEY" \
  --data-urlencode "org=$KINESIS_ORG"
```

Omit it only when the credential reaches one organization. With several, a call needing one organization fails with `org_required`; `error.details.orgs` lists the choices. `GET /projects` and `GET /apps` without `org` list across reachable organizations; supplying it narrows the list.

## Permission scopes

| Scope             | What it permits, subject to the person's role                            |
| ----------------- | ------------------------------------------------------------------------ |
| `projects:read`   | Read accessible projects                                                 |
| `projects:write`  | Create and update projects                                               |
| `projects:admin`  | Delete projects and manage project access                                |
| `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 access                                |
| `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 access                                      |
| `monitoring:read` | Read usage, app logs, build logs and server logs                         |
| `vcs:read`        | Browse connected GitHub accounts and repositories                        |
| `billing:read`    | Read balance, costs, invoices, ledger and payment settings               |
| `billing:write`   | Change payment settings, redeem vouchers and create REST payments        |
| `members:read`    | Read members and pending organization invitations; see resource creators |
| `members:write`   | Invite/remove members, change roles and transfer ownership               |
| `org:write`       | Create organizations, rename them and change their settings              |
| `audit:read`      | Read the organization's audit log, including member identities           |
| `account:read`    | Read personal notifications and received invitations                     |
| `account:write`   | Manage notifications, answer invitations and leave shared resources      |
| `compute:spend`   | Authorize actions that start, resize or provision compute                |

Within a family, `admin` includes `write` and `read`, and `write` includes `read`. `compute:spend` is separate. So is the `audit` family: `org:write` does **not** grant `audit:read`. Grid scopes retain the name `pools`.

The reference lists exact scope combinations and input-dependent conditions. Creating, starting or restarting an app needs `apps:write` and `compute:spend`. Scopes authorize spending from the organization's balance within its role and compute controls.

## Resource access and creator identity

Projects and grids expose organization and visibility; projects, apps and grids include effective `access` (`role`, `outside`, `isCreator`) and `createdBy`. Apps follow their project. `createdBy` contains `userId`, `name` and `email`, or is null when the credential lacks `members:read` or the person is not a member of the resource's organization.

Admins manage every resource in their organization. Developers edit and operate apps they can access as Developer, and delete projects/apps they created. Admins or the creator manage project/app access; only admins manage grids and servers. Organization billing is admin-only.

Resource sharing uses `viewer` / `editor` in payloads; `editor` means Developer in the portal. Organization membership uses `viewer` / `developer` / `admin`. See [Sharing and visibility](/organizations/sharing.md).

## Restrictions on credentials

| Restriction                      | Effect                                                                                                                                |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Chosen organizations             | Acts only in those organizations while the person remains a member                                                                    |
| Specific projects                | Acts only on those projects and their apps; cannot create projects or run organization-wide infrastructure, billing or administration |
| Chosen organizations or projects | Cannot create an organization or accept/decline an invitation to join one                                                             |

Project-limited keys have narrow read exceptions: `get_org` reads the relevant organization, `list_members` supports sharing those projects, and costs require an explicit permitted `projectId` and an Admin organization role. Member activity/count details are omitted even for an admin using a project-limited key. These exceptions do not permit member administration or audit access. Disallowed operations return `key_project_restricted`; organization-limited operations outside their allowed scope are refused as `forbidden`.

Removing a member ends credential access in that organization. A credential limited to it loses it from its selection and is revoked if none remain. Resources and running apps remain with the organization.

## Single sign-on and credentials

Requiring organization SSO gates browser access; existing API keys and connected apps keep their access until membership, permissions, expiry or revocation changes. They do not require browser SSO renewal every 24 hours. Creating a key, changing its organization/project reach or approving a new connection checks the browser session’s access to each selected organization; complete its SSO when prompted. See [Single sign-on](/organizations/single-sign-on.md).

## OAuth and MCP

MCP connections can use OAuth or an API key. An OAuth connection acts as its person with approved scopes and can be limited to chosen organizations on the consent page. Its access token is valid for MCP only; use an API key for REST.

Connections approved before the organization scopes existed must be re-approved to use them. `insufficient_scope` names the required permissions; changing catalog mode or filters does not grant them. See [OAuth for MCP clients](/mcp/oauth.md).

For failures, follow [Errors and recovery](/api/errors.md). Include a request ID when available in support reports, never the credential itself.


---

# 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.kinesis.network/api/authentication.md?ask=<question>&goal=<user_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.