Permissions

---

User roles

Every user in an organization is assigned a role. Roles determine which actions a user can perform in the dashboard and API.

Built-in roles

How roles are checked

When a user makes a request, Senso resolves their role in the current organization and checks whether that role includes the required permission. Admins bypass all permission checks — they always have full access.

Users who are super admins or belong to a partner organization are also treated as effective admins.

Available permissions

Permissions follow the pattern action:resource. An organization's roles can include any combination of these:

API key access

Organization API keys authenticate requests to the Senso API. By default, an API key has full access to all org-level endpoints (query, ingest, generate, etc.) but no knowledge base access until you either leave it unscoped (full KB access) or grant it specific folders.

Default behaviour

When you create an API key from the API Keys page, it starts unscoped — meaning it can access the entire knowledge base. This is the simplest setup for internal tools and trusted integrations.

Scoping a key to specific folders

You can restrict an API key so it can only see specific parts of your knowledge base. This is useful when you want to give an external integration access to "Public Docs" but not "Internal Policies."

When a key is scoped:

You can configure KB scope from the API Keys page by clicking "Configure" in the KB Access column, or through the API:

import os, requests

KEY  = os.environ["SENSO_API_KEY"]
BASE = "https://apiv2.senso.ai/api/v1"
HEADERS = {"X-API-Key": KEY, "Content-Type": "application/json"}

# Scope a key to specific folders
requests.put(f"{BASE}/org/api-keys/{key_id}/kb-permissions", headers=HEADERS, json={
    "grants": [
        {"node_id": public_folder_id, "role": "viewer"},
        {"node_id": uploads_folder_id, "role": "editor"},
    ]
})

# Check what a key has access to
resp = requests.get(f"{BASE}/org/api-keys/{key_id}/kb-permissions", headers=HEADERS)
for grant in resp.json():
    print(f"  {grant['node_id']}: {grant['role']}")

# Remove all restrictions (restore full KB access)
requests.delete(f"{BASE}/org/api-keys/{key_id}/kb-permissions", headers=HEADERS)

# Scope a key to specific folders
curl -X PUT https://apiv2.senso.ai/api/v1/org/api-keys/{keyId}/kb-permissions \
  -H "X-API-Key: $SENSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grants": [{"node_id": "FOLDER_ID", "role": "viewer"}]}'

# Check scope
curl https://apiv2.senso.ai/api/v1/org/api-keys/{keyId}/kb-permissions \
  -H "X-API-Key: $SENSO_API_KEY"

# Remove scope (restore full access)
curl -X DELETE https://apiv2.senso.ai/api/v1/org/api-keys/{keyId}/kb-permissions \
  -H "X-API-Key: $SENSO_API_KEY"

---

Knowledge base roles

When granting an API key (or user) access to a KB folder, you assign one of these roles:

Permission inheritance

Permissions flow downward through the folder tree. A grant on a parent folder automatically applies to all files and subfolders inside it — you don't need to set permissions on each item individually.

Root
├── Public Docs/          ← API key granted "viewer" here
│   ├── faq.pdf           ← inherits "viewer"
│   └── Guides/           ← inherits "viewer"
│       └── setup.md      ← inherits "viewer"
├── Internal/             ← no grant → no access
│   └── roadmap.docx      ← no access

If a key has grants on multiple folders, the most permissive role wins when a node is accessible through more than one path.

---

Putting it together

Here's how the two layers interact:

Tip: Create separate API keys for each agent or integration, scoped to only the folders it needs. This way, revoking one key doesn't affect your other agents.

---

Listing available permissions

Use GET /org/permissions to list all available permissions you can assign to custom roles:

# Get available permissions
resp = requests.get(f"{BASE}/org/permissions", headers=HEADERS)
print(resp.json())

# List available permissions
curl https://apiv2.senso.ai/api/v1/org/permissions \
  -H "X-API-Key: $SENSO_API_KEY"

You can also list available permissions with the CLI:

senso permissions list

---

Next steps