Open the console
Additional

Roles and permissions

What each built-in role and an API key may do, permission by permission, and which API routes require each one.

Every route on the CoreValue API names one permission it requires, and every role is a set of permissions. Both are declared in code, so this page is rendered from that declaration rather than written beside it.

Built-in roles

An organisation has three built-in roles. They mean the same thing in every organisation and cannot be edited.

  • Owner holds every permission, including the four ownership actions: transfer the organisation, delete it, cancel the subscription and remove a payment method. There is one owner per organisation, and ownership moves only by transfer.
  • Admin holds everything except ownership.
  • Member reads traffic and annotates it: traffic.read and traffic.annotate.

Every role, and every API key, holds org.read: the organisation you belong to, its entitlements and settings reads. It is what lets a person open the console at all, and no role can drop it.

API keys carry no role. A key holds exactly what a member holds and nothing above it, whichever role the person who created it has. What a key may do is bounded separately, by the permissions set on the key itself.

Custom roles are an Enterprise feature. The catalogue below is what a custom role is built from: any permission except ownership, which no role can be given.

The permission catalogue

PermissionWhat it allowsOwnerAdminMemberAPI key
org.readOpen the organisation: its settings, entitlements and terms. Every role holds this.✓✓✓✓
traffic.readDashboards, requests, sessions, metrics, properties, MCP and A2A views.✓✓✓✓
traffic.annotateFeedback, scores, tags and a request's custom property.✓✓✓✓
org.settings.writeOrganisation details, onboarding, PII and retention config, saved views.✓✓——
org.members.writeInvite, change roles, remove; teams and their membership; visibility mode.✓✓——
spend_controls.writeBudgets at every scope, key caps, alerts, downgrade mappings, rate limits, prices and declared value.✓✓——
gateway_config.writeFallback chains, cache and routing.✓✓——
keys.writeAPI keys, proxy keys and their scopes.✓✓——
provider_keys.writeProvider keys and the vault.✓✓——
egress.writeWebhooks and integrations: data leaving the organisation.✓✓——
governance.writeAccess rules, MCP and A2A registries.✓✓——
reports.readChargeback, unit economics, value, the budget summary, the breach log, invoices, spend by model, and customer budgets and prices.✓✓——
audit.readRead the organisation's audit log and export it.✓✓——
billing.writeCheckout, upgrades, add-ons and payment setup.✓✓——
playground.useChat with models and MCP tools in the console playground, spending as yourself.✓✓——
ownershipTransfer, delete the organisation, cancel the subscription, remove a payment method. The owner only; no role can hold it.✓———

Routes by permission

Which API routes require each permission. A path segment in braces is a parameter. A route that does not appear here is not gated on a role.

org.read

  • GET /v1/a2a/agents
  • GET /v1/api-keys/scopes/entitlement
  • GET /v1/governance/access-default
  • GET /v1/governance/access-rules
  • POST /v1/governance/access-rules/audit
  • GET /v1/governance/entitlement
  • GET /v1/mcp-connections
  • POST /v1/mcp-connections/authorize
  • POST /v1/mcp-connections/consent
  • GET /v1/mcp-connections/settings
  • DELETE /v1/mcp-connections/{grantId}
  • GET /v1/mcp/servers
  • POST /v1/mcp/upstream/connect
  • GET /v1/mcp/upstream/connect/{handle}
  • POST /v1/mcp/upstream/connect/{handle}/continue
  • GET /v1/mcp/upstream/connections
  • DELETE /v1/mcp/upstream/connections/{connectionId}
  • POST /v1/organization/user/accept_terms
  • GET /v1/organization/{id}/permissions/me
  • GET /v1/organization/{id}/roles
  • GET /v1/organization/{id}/roles/entitlement
  • GET /v1/organization/{id}/sso/entitlement
  • GET /v1/team
  • GET /v1/team/settings/visibility
  • GET /v1/team/{teamId}/members
  • GET /v1/tool-rates

traffic.read

  • POST /v1/a2a/calls
  • POST /v1/a2a/summary
  • POST /v1/budget/actions/breakdown
  • POST /v1/budget/actions/over-time
  • POST /v1/dashboard/scores/query
  • POST /v1/dashboard/verdicts
  • POST /v1/mcp/filter-options
  • POST /v1/mcp/summary
  • POST /v1/mcp/tool-calls
  • POST /v1/metrics/activeUsers
  • POST /v1/metrics/averageLatency
  • POST /v1/metrics/averageTimeToFirstToken
  • POST /v1/metrics/averageTokensPerRequest
  • POST /v1/metrics/cacheSavings
  • POST /v1/metrics/costEfficiency
  • POST /v1/metrics/costOverTime
  • POST /v1/metrics/costPerTokenOverTime
  • POST /v1/metrics/country
  • POST /v1/metrics/errorBreakdown
  • POST /v1/metrics/errorOverTime
  • POST /v1/metrics/latencyOverTime
  • POST /v1/metrics/models
  • POST /v1/metrics/modelsOverTime
  • POST /v1/metrics/propertyAggregation
  • POST /v1/metrics/quantiles
  • POST /v1/metrics/requestCount
  • POST /v1/metrics/requestOverTime
  • POST /v1/metrics/requestStatusOverTime
  • POST /v1/metrics/spendTrend
  • POST /v1/metrics/threatsOverTime
  • POST /v1/metrics/timeToFirstToken
  • POST /v1/metrics/tokensOverTime
  • POST /v1/metrics/totalCost
  • POST /v1/metrics/totalRequests
  • POST /v1/metrics/totalThreats
  • POST /v1/metrics/usersOverTime
  • POST /v1/property/hidden/query
  • POST /v1/property/properties/over-time
  • POST /v1/property/query
  • POST /v1/property/{propertyKey}/search
  • POST /v1/property/{propertyKey}/top-costs/query
  • POST /v1/property/{propertyKey}/top-requests/query
  • POST /v1/providers
  • POST /v1/request/count/query
  • POST /v1/request/query
  • POST /v1/request/query-clickhouse
  • POST /v1/request/query-ids
  • POST /v1/request/{requestId}/assets/{assetId}
  • POST /v1/security/pii/over-time
  • POST /v1/security/pii/recent
  • POST /v1/security/pii/summary
  • POST /v1/session/query
  • POST /v1/spend/by
  • POST /v1/test/gateway-request
  • POST /v1/user/metrics-overview/query
  • POST /v1/user/metrics/query
  • POST /v1/user/query

traffic.annotate

  • POST /v1/request/{requestId}/feedback
  • PUT /v1/request/{requestId}/property
  • POST /v1/request/{requestId}/score
  • POST /v1/session/{sessionId}/feedback
  • POST /v1/session/{sessionId}/tag

org.settings.write

  • POST /v1/filter
  • DELETE /v1/filter/{id}
  • PATCH /v1/filter/{id}
  • PUT /v1/mcp-connections/settings
  • POST /v1/organization/body-retention-config
  • POST /v1/organization/onboard
  • POST /v1/organization/pii-config
  • POST /v1/organization/update_onboarding
  • POST /v1/organization/{id}/create_filter
  • DELETE /v1/organization/{id}/sso
  • GET /v1/organization/{id}/sso
  • PUT /v1/organization/{id}/sso
  • POST /v1/organization/{id}/sso/test
  • POST /v1/organization/{id}/sso/verify-domain
  • POST /v1/organization/{id}/update
  • POST /v1/organization/{id}/update_filter
  • POST /v1/property/hide
  • POST /v1/property/restore

org.members.write

  • POST /v1/organization/{id}/add_member
  • DELETE /v1/organization/{id}/remove_member
  • POST /v1/organization/{id}/roles
  • PATCH /v1/organization/{id}/roles/{roleId}
  • POST /v1/organization/{id}/roles/{roleId}/archive
  • POST /v1/organization/{id}/update_member
  • POST /v1/team
  • PUT /v1/team/settings/visibility
  • DELETE /v1/team/{teamId}
  • PUT /v1/team/{teamId}
  • DELETE /v1/team/{teamId}/member
  • POST /v1/team/{teamId}/member

spend_controls.write

  • DELETE /v1/budget/alert-config
  • PUT /v1/budget/alert-config
  • POST /v1/budget/breach
  • DELETE /v1/budget/customer
  • PUT /v1/budget/customer
  • DELETE /v1/budget/customer-price
  • PUT /v1/budget/customer-price
  • POST /v1/budget/downgrade-mappings
  • DELETE /v1/budget/downgrade-mappings/{mappingId}
  • PUT /v1/budget/member/{memberUserId}
  • POST /v1/budget/notify
  • PUT /v1/budget/velocity-limit
  • DELETE /v1/budget/velocity-limit/{id}
  • PUT /v1/budget/window-limit
  • DELETE /v1/budget/window-limit/{id}
  • PUT /v1/budget/window-settings
  • POST /v1/chargeback/{month}/close
  • DELETE /v1/model-prices
  • PUT /v1/model-prices
  • PUT /v1/model-prices/import
  • POST /v1/rate-limits
  • DELETE /v1/rate-limits/{ruleId}
  • PUT /v1/rate-limits/{ruleId}
  • POST /v1/recommendations/{recommendationId}/apply
  • POST /v1/recommendations/{recommendationId}/dismiss
  • PUT /v1/tool-rates
  • DELETE /v1/tool-rates/{id}
  • DELETE /v1/value/rate
  • PUT /v1/value/rate

gateway_config.write

  • POST /v1/gateway/fallback-chains
  • DELETE /v1/gateway/fallback-chains/{chainId}
  • PUT /v1/gateway/fallback-chains/{chainId}

keys.write

  • POST /v1/api-keys
  • POST /v1/api-keys/proxy-key
  • PUT /v1/api-keys/proxy-key/{proxyKeyId}/scopes
  • DELETE /v1/api-keys/{apiKeyId}
  • PATCH /v1/api-keys/{apiKeyId}
  • PUT /v1/api-keys/{apiKeyId}/scopes
  • GET /v1/mcp-connections/org
  • GET /v1/mcp/upstream/connections/org

provider_keys.write

  • POST /v1/api-keys/provider-key
  • DELETE /v1/api-keys/provider-key/{providerKeyId}
  • GET /v1/api-keys/provider-key/{providerKeyId}
  • PATCH /v1/api-keys/provider-key/{providerKeyId}
  • GET /v1/api-keys/provider-keys
  • POST /v1/vault/add
  • GET /v1/vault/key/{providerKeyId}
  • GET /v1/vault/keys
  • PATCH /v1/vault/update/{id}

egress.write

  • GET /v1/integration
  • POST /v1/integration
  • GET /v1/integration/slack/channels
  • GET /v1/integration/slack/settings
  • GET /v1/integration/type/{type}
  • GET /v1/integration/{integrationId}
  • POST /v1/integration/{integrationId}
  • POST /v1/integration/{integrationId}/stripe/test-meter-event
  • GET /v1/webhooks
  • POST /v1/webhooks
  • DELETE /v1/webhooks/{webhookId}
  • POST /v1/webhooks/{webhookId}/test

governance.write

  • POST /v1/a2a/agents
  • DELETE /v1/a2a/agents/{id}
  • PATCH /v1/a2a/agents/{id}
  • PUT /v1/a2a/agents/{id}/keys
  • POST /v1/a2a/agents/{id}/probe
  • PUT /v1/governance/access-default
  • POST /v1/governance/access-rules
  • DELETE /v1/governance/access-rules/{id}
  • PATCH /v1/governance/access-rules/{id}
  • PUT /v1/mcp/platform-servers/{serverId}
  • POST /v1/mcp/servers
  • POST /v1/mcp/servers/discover
  • DELETE /v1/mcp/servers/{id}
  • PATCH /v1/mcp/servers/{id}
  • POST /v1/mcp/servers/{id}/probe

reports.read

  • GET /v1/budget/breaches
  • GET /v1/budget/customer-prices
  • GET /v1/budget/customers
  • GET /v1/budget/summary
  • GET /v1/chargeback/{month}
  • GET /v1/credits/invoices
  • GET /v1/credits/spend/breakdown
  • GET /v1/unit-economics
  • GET /v1/value
  • GET /v1/value/rates

audit.read

  • GET /v1/organization/{id}/audit
  • GET /v1/organization/{id}/audit.csv

billing.write

  • POST /v1/stripe/cloud/checkout-session
  • POST /v1/stripe/payment-methods/setup-session
  • DELETE /v1/stripe/subscription/add-ons/{productType}
  • POST /v1/stripe/subscription/add-ons/{productType}
  • POST /v1/stripe/subscription/existing-customer/upgrade-to-growth
  • POST /v1/stripe/subscription/new-customer/upgrade-to-growth
  • POST /v1/stripe/subscription/undo-cancel-subscription

playground.use

  • GET /v1/playground/options
  • POST /v1/playground/servers/{serverId}/tools-check
  • POST /v1/playground/step

ownership

  • DELETE /v1/organization/delete
  • PUT /v1/organization/{id}/sso/enforce
  • POST /v1/organization/{id}/update_owner
  • DELETE /v1/stripe/payment-methods/{paymentMethodId}
  • POST /v1/stripe/subscription/cancel-subscription
  • POST /v1/stripe/subscription/manage-subscription
  • POST /v1/stripe/subscription/migrate-to-pro

Generated from server/core/src/lib/authz/permissions.ts and middleware/rbac.ts; do not edit by hand.

On this page

Built-in rolesThe permission catalogueRoutes by permissionorg.readtraffic.readtraffic.annotateorg.settings.writeorg.members.writespend_controls.writegateway_config.writekeys.writeprovider_keys.writeegress.writegovernance.writereports.readaudit.readbilling.writeplayground.useownership