Skip to content
Truss Docs

Authorization

Truss provides relation-based access control (ReBAC) powered by Ory Keto. This lets you define who can do what to which resource using relation tuples — a flexible model that handles RBAC, ABAC, and hierarchical permissions.

Setup

KETO_READ_URL=http://localhost:4466
KETO_WRITE_URL=http://localhost:4467
KETO_ADMIN_TOKEN=your-admin-token

Concepts

Authorization in Truss is based on relation tuples:

namespace:object#relation@subject

For example:

  • Organization:acme#member@user123 — user123 is a member of Acme org
  • Project:website#editor@user456 — user456 can edit the website project
  • Project:website#viewer@Organization:acme#member — all Acme members can view the website

Namespaces

Truss ships with three default namespaces:

  • User — individual users
  • Organization — groups with members and admins
  • Project — resources with owners, editors, and viewers

Dashboard

The dashboard provides three authorization views:

  • Permissions — check permissions and manage relation tuples
  • Roles — visual matrix of who has what role where
  • Namespaces — OPL (Ory Permission Language) reference

Checking permissions

Terminal window
# Check if a user has a relation on an object
curl -X POST http://localhost:4466/relation-tuples/check \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "Project",
    "object": "website",
    "relation": "editor",
    "subject_id": "user123"
  }'

Response: {"allowed": true} or {"allowed": false}.

Managing relation tuples

Create a tuple

Terminal window
curl -X PUT http://localhost:4467/admin/relation-tuples \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-admin-token" \
  -d '{
    "namespace": "Project",
    "object": "website",
    "relation": "editor",
    "subject_id": "user123"
  }'

Delete a tuple

Terminal window
curl -X DELETE "http://localhost:4467/admin/relation-tuples?namespace=Project&object=website&relation=editor&subject_id=user123" \
  -H "Authorization: Bearer your-admin-token"

Batch operations (via Truss API)

Terminal window
# Bulk import tuples (up to 500)
curl -X POST http://localhost:8787/api/keto/relation-tuples/import \
  -H "Content-Type: application/json" \
  -d '{
    "tuples": [
      {"namespace": "Project", "object": "website", "relation": "viewer", "subject_id": "user1"},
      {"namespace": "Project", "object": "website", "relation": "viewer", "subject_id": "user2"}
    ]
  }'


# Bulk delete tuples
curl -X POST http://localhost:8787/api/keto/relation-tuples/batch-delete \
  -H "Content-Type: application/json" \
  -d '{"tuples": [...]}'

Querying relations

Get all tuples for a subject

Terminal window
curl http://localhost:8787/api/keto/subject-tuples/user123

Returns all relation tuples where user123 is the subject, across all namespaces.

Who can access an object?

Terminal window
curl -X POST http://localhost:8787/api/keto/who-can-access \
  -H "Content-Type: application/json" \
  -d '{"namespace": "Project", "object": "website"}'

Returns all subjects with access, their relations, and a permission matrix.

Subject sets (indirect permissions)

You can grant permissions to groups, not just individuals:

{
  "namespace": "Project",
  "object": "website",
  "relation": "viewer",
  "subject_set": {
    "namespace": "Organization",
    "object": "acme",
    "relation": "member"
  }
}

This means: anyone who is a member of Organization:acme is automatically a viewer of Project:website.