permissions

Give Capability To Principal

Grant one or more capabilities to a principal: a user, a role, or a whole tenant.

Granting to the tenant reaches every current and future member; granting to a role reaches its members; granting to a user reaches that person in the given tenant only. The same endpoint serves all three because a capability row is (principal, tenant, capability) regardless of what the principal is.

The caller needs the grant_capabilities capability in the target tenant, and must hold every capability they grant: granting passes on what the caller has, never more. The tenant owner holds everything, which is how the first grant gets made. The caller is recorded as the granter of each new grant.

Several capabilities can be granted in one call by repeating the capability parameter. The batch is all or nothing: an unknown name rejects the whole request and nothing is written. Granting is idempotent.

Error Codes

400 Bad Request: A capability is not in the catalog
403 Forbidden: Caller lacks grant_capabilities in the target tenant, or the principal or tenant does not exist. These answer the same, so the endpoint cannot be used to discover which ids are real. Also when the caller does not hold a capability they try to grant, or the principal is a user who is not a member of the tenant (that one says so: add the user to the tenant first)

POST

api

permissions

capabilities

{principal_id}

Give Capability To Principal

curl --request POST \
  --url https://{tenant}.aws.cognee.ai/api/v1/permissions/capabilities/{principal_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/permissions/capabilities/{principal_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

principal_id

string<uuid>

required

Query Parameters

capability

string[]

required

Capability to grant. Must be in the capability catalog. Repeat the parameter to grant several at once: ?capability=a&capability=b.

Example:

["manage_users"]

tenant_id

string<uuid> | null

Tenant the grant is scoped to when the principal is a user. Defaults to the caller's current tenant. Ignored for a role or a tenant, whose own tenant is always used.

Response

Successful Response

⌘I

Give Capability To Principal

curl --request POST \
  --url https://{tenant}.aws.cognee.ai/api/v1/permissions/capabilities/{principal_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://{tenant}.aws.cognee.ai/api/v1/permissions/capabilities/{principal_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Getting Started

auth

add

cognify

memify

search

permissions

datasets

ontologies

settings

visualize

schema

skills

configuration

delete

validate

update

responses

llm

sync

users

checks

health

agent management

agent connections

activity

sessions

remember

recall

improve

forget

slack

integrations

Give Capability To Principal

Error Codes

Authorizations

Path Parameters

Query Parameters

Response