List Roles

GET /v1/roles

Returns your tenant’s permission roles. This is the endpoint that makes role_ids usable from code: a Terraform module or a provisioning script cannot hard-code a per-tenant UUID, and before this existed the only way to find one was to open the admin UI and copy it out of the URL bar. Read-only, permanently. There is no POST, PATCH or DELETE on /v1/roles.

Only the seeded key roles (seeded: true) are accepted in role_ids. Custom roles are being retired in favour of per-key permissions: no new one can be created, and this list still returns any your tenant already has (seeded: false) — POST /v1/api-keys refuses those with 403 forbidden. Filter on seeded when choosing a role.

Requires the role:list permission, which all four seeded machine roles carry.

Query Parameters

Parameter	Type	Description
`subject_kind`	string	`api_key` or `user`. Returns only roles whose `applies_to` includes it. With `api_key`, the rows you can attach to a key are the ones with `seeded: true`. Any other value is a `400`.
`page`	integer	Page number (default `1`)
`per_page`	integer	Results per page (default `20`, max `100`)

Response

{
  "data": [
    {
      "id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "name": "Key — Infrastructure",
      "description": "For Terraform and other infrastructure-as-code runners.",
      "applies_to": ["api_key"],
      "is_default": false,
      "seeded": true
    },
    {
      "id": "c4e2d3f5-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
      "name": "Key — Read-only",
      "description": "List/read config and analytics/log metadata.",
      "applies_to": ["api_key"],
      "is_default": true,
      "seeded": true
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Field	Description
`applies_to`	Subject kinds the role may be assigned to. Passing a role whose `applies_to` is `["user"]` in `role_ids` returns a `400`.
`is_default`	Whether the admin UI prefills this role when creating a key.
`seeded`	`true` for roles KnoxCall creates and maintains. Seeded roles cannot be deleted, renamed or recomposed. Only a seeded key role is accepted in `role_ids`; `false` marks a custom role, which is being retired.

The rules a role grants are deliberately not returned. Enumerating them would hand every machine credential in the tenant a map of your authorization surface. To see what a role grants, open it in the admin UI.

The seeded machine roles

Role	For
`Key — Invoke`	Intended for keys that call your APIs: reads the route/client/environment config needed to resolve a target, and runs workflows. No writes. Holding it is not what lets a key call a route — see the warning below.
`Key — Read-only`	List/read config and analytics metadata. The default for a fresh key. It does not stop the key calling your routes — see the warning below.
`Key — Editor`	CRUD on routes, clients, environments, webhooks and secrets. No key management, no billing, no permissions.
`Key — Infrastructure`	Terraform and other infrastructure-as-code runners. The whole provisioning surface: routes, environments, secrets, clients, API keys, webhooks, workflows, vaults, PKI, dynamic DB credentials, transit keys, AI gateways, OAuth clients and agents.

No role restricts which routes a key can call. Roles are enforced on the /v1 management API. The proxy does not evaluate them: any active key can call any enabled route in its mode (Live or Test), whatever roles it holds — so Key — Invoke and Key — Read-only behave identically on proxied calls today. Contain proxied use with each route’s Require authorized clients setting and IP allowlist, and with routes:invoke scopes on OAuth access tokens, which the proxy does enforce.

Key — Infrastructure deliberately excludes, and explicitly denies:

secret:reveal — a provisioning credential never needs the plaintext of a secret it created. KnoxCall holds the plaintext; that is the product.
secret:custody_enable / custody_disable / custody_rotate — custody transitions decrypt the current administrative credential server-side.
workload_binding:create / delete — a binding is a permanent route to a live credential for anyone presenting a matching JWT.
ephemeral_proxy:invoke — one-shot runtime invocation against live credentials. It is not infrastructure state, and no Terraform resource models it.

None of those four can be reached by a wildcard rule either: they require an exact (resource_type, action) allow, so a legacy *:* key does not silently hold them.

Excluding secret:reveal does not make an Infrastructure key plaintext-free. It still holds operations that return plaintext or mint live credentials by design — transit:decrypt, vault:detokenize, secret:oauth_token_get, pki:issue (the leaf certificate’s private key), dyn_db_cred:mint and ai_gateway:mint — and it can create and update routes and workflows, which inject your secrets into the requests they send. Re-pointing one at another host sends the secret there. Treat an Infrastructure key as able to reach your secrets, and store it accordingly.

Examples

# $TOKEN is a minted OAuth access token — see /api-reference/authentication
curl "https://api.knoxcall.com/v1/roles?subject_kind=api_key" \
  -H "Authorization: Bearer $TOKEN"

from knoxcall import KnoxCall

kc = KnoxCall(tenant="acme")
roles = kc.roles.list(subject_kind="api_key")["data"]
infra = next(r for r in roles if r["name"] == "Key — Infrastructure")

key = kc.api_keys.create(name="terraform-prod", role_ids=[infra["id"]])
print(key["api_key"])  # shown once

import { KnoxCall } from "@knoxcall/sdk";

const kc = new KnoxCall({ tenant: "acme" });
const { data: roles } = await kc.roles.list({ subject_kind: "api_key" });
const infra = roles.find((r) => r.name === "Key — Infrastructure")!;

const key = await kc.apiKeys.create({ name: "terraform-prod", role_ids: [infra.id] });
console.log(key.api_key); // shown once

Errors

Status	Type	Description
400	`validation_error`	`subject_kind` was neither `api_key` nor `user`
403	`forbidden`	The calling key does not hold `role:list`

Overview

Workload Identity

Routes

Secrets

Clients

Environments

API Keys

Webhooks

Ephemeral Proxy

AI Gateway

Audit Logs

Account

Tenant KMS

Secret Store Migrations

Changelog

List Roles

List Roles

Query Parameters

Response

The seeded machine roles

Examples

Errors

​List Roles

​Query Parameters

​Response

​The seeded machine roles

​Examples

​Errors

List Roles

Query Parameters

Response

The seeded machine roles

Examples

Errors