Authentication and scopes

API keys, organization selection, scopes and resource access.

REST requests use an API key in the HTTP header:

Authorization: Bearer kn_your_api_key

Create and manage keys under API keys in Account settings. 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.

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.

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.

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.

For failures, follow Errors and recovery. Include a request ID when available in support reports, never the credential itself.