Permissions API

• Base URL: https://permissions.sls.epilot.io
• API Docs: https://docs.epilot.io/api/permissions

Flexible Role-based Access Control for epilot

Quick Start

# List available operations
epilot permissions

# Call an operation
epilot permissions listCurrentRoles

Common Flags

Flag	Description
-p key=value	Set a named parameter
-d '{...}'	Request body JSON
-H 'Key: Value'	Custom header
-t, --token <token>	Bearer token for authentication
--profile <name>	Use a named profile
-s, --server <url>	Override server base URL
-i, --include	Include response headers in output
--json	Output raw JSON (no formatting)
-v, --verbose	Verbose output (show request details)
--jsonata <expr>	JSONata expression to transform response
--definition <file>	Override OpenAPI spec file/URL
--guided	Prompt for all parameters interactively
--no-interactive	Disable interactive prompts

Operations

Roles

• listCurrentRoles — Returns roles and grants assigned to current user
• listAllRoles — Returns list of all roles in organization
• createRole — Create role
• searchRoles — Search Roles
• getRole — Get role by id
• putRole — Create or update role
• deleteRole — Delete role by id
• refreshPermissions — Makes sure the user has a role in the organization

Assignments

• getAssignedRolesForUser — Get list of assigned roles by user id
• assignRoles — Assign / unassign roles to users.
• addAssignment — Assign a user to a role.
• removeAssignment — Remove role assignment from user
• listAllAssignments — Returns list of all assignments in organization

listCurrentRoles

Returns roles and grants assigned to current user

GET /v1/permissions/me

Sample Call

epilot permissions listCurrentRoles

With JSONata filter:

epilot permissions listCurrentRoles --jsonata 'roles'

Sample Response

{
  "roles": [
    {
      "id": "123:owner",
      "name": "Owner",
      "slug": "owner",
      "type": "user_role",
      "expires_at": "2028-07-21T17:32:28Z",
      "organization_id": "123",
      "grants": [
        {
          "action": "entity-read",
          "resource": "entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947",
          "effect": "allow",
          "conditions": [
            {
              "attribute": "workflows.primary.task_name",
              "operation": "equals",
              "values": ["Qualification"]
            }
          ]
        }
      ],
      "parent_role": "123:owner"
    }
  ]
}

---

listAllRoles

Returns list of all roles in organization

GET /v1/permissions/roles

Sample Call

epilot permissions listAllRoles

With JSONata filter:

epilot permissions listAllRoles --jsonata 'roles'

Sample Response

{
  "roles": [
    {
      "id": "123:owner",
      "name": "Owner",
      "slug": "owner",
      "type": "user_role",
      "expires_at": "2028-07-21T17:32:28Z",
      "organization_id": "123",
      "grants": [
        {
          "action": "entity-read",
          "resource": "entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947",
          "effect": "allow",
          "conditions": [
            {
              "attribute": "workflows.primary.task_name",
              "operation": "equals",
              "values": ["Qualification"]
            }
          ]
        }
      ],
      "parent_role": "123:owner"
    }
  ]
}

---

createRole

Create role

POST /v1/permissions/roles

Request Body

Sample Call

epilot permissions createRole \
  -d '{}'

Using stdin pipe:

cat body.json | epilot permissions createRole

With JSONata filter:

epilot permissions createRole --jsonata '$'

Sample Response

{
  "id": "123:owner",
  "name": "Owner",
  "slug": "owner",
  "type": "user_role",
  "expires_at": "2028-07-21T17:32:28Z",
  "organization_id": "123",
  "grants": [
    {
      "action": "entity-read",
      "resource": "entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947",
      "effect": "allow",
      "conditions": [
        {
          "attribute": "workflows.primary.task_name",
          "operation": "equals",
          "values": ["Qualification"]
        }
      ]
    }
  ],
  "parent_role": "123:owner"
}

---

searchRoles

Search Roles

POST /v1/permissions/roles:search

Request Body

Sample Call

epilot permissions searchRoles

With request body:

epilot permissions searchRoles \
  -d '{
  "role_ids": ["123:manager", "456:owner"],
  "org_ids": ["123", "456"],
  "slugs": ["manager", "owner"],
  "query": "Administrator",
  "limit": 1,
  "offset": 1
}'

Using stdin pipe:

cat body.json | epilot permissions searchRoles

With JSONata filter:

epilot permissions searchRoles --jsonata 'results[0]'

Sample Response

{
  "hits": 0,
  "results": [
    {
      "id": "123:owner",
      "name": "Owner",
      "slug": "owner",
      "type": "user_role",
      "expires_at": "2028-07-21T17:32:28Z",
      "organization_id": "123",
      "grants": [
        {
          "action": "entity-read",
          "resource": "entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947",
          "effect": "allow",
          "conditions": [
            {
              "attribute": "workflows.primary.task_name",
              "operation": "equals",
              "values": ["Qualification"]
            }
          ]
        }
      ],
      "parent_role": "123:owner"
    }
  ]
}

---

getRole

Get role by id

GET /v1/permissions/roles/{roleId}

Parameters

Name	In	Type	Required	Description
roleId	path	string	Yes

Sample Call

epilot permissions getRole \
  -p roleId=123:owner

Using positional args for path parameters:

epilot permissions getRole 123:owner

With JSONata filter:

epilot permissions getRole -p roleId=123:owner --jsonata '$'

Sample Response

{
  "id": "123:owner",
  "name": "Owner",
  "slug": "owner",
  "type": "user_role",
  "expires_at": "2028-07-21T17:32:28Z",
  "organization_id": "123",
  "grants": [
    {
      "action": "entity-read",
      "resource": "entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947",
      "effect": "allow",
      "conditions": [
        {
          "attribute": "workflows.primary.task_name",
          "operation": "equals",
          "values": ["Qualification"]
        }
      ]
    }
  ],
  "parent_role": "123:owner"
}

---

putRole

Create or update role

PUT /v1/permissions/roles/{roleId}

Parameters

Name	In	Type	Required	Description
roleId	path	string	Yes

Request Body

Sample Call

epilot permissions putRole \
  -p roleId=123:owner

With request body:

epilot permissions putRole \
  -p roleId=123:owner \
  -d '{
  "id": "123:owner",
  "name": "Owner",
  "slug": "owner",
  "type": "user_role",
  "expires_at": "2028-07-21T17:32:28Z",
  "organization_id": "123",
  "grants": [
    {
      "action": "entity-read",
      "resource": "entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947",
      "effect": "allow",
      "conditions": [
        {
          "attribute": "workflows.primary.task_name",
          "operation": "equals",
          "values": ["Qualification"]
        }
      ]
    }
  ],
  "parent_role": "123:owner"
}'

Using positional args for path parameters:

epilot permissions putRole 123:owner

Using stdin pipe:

cat body.json | epilot permissions putRole -p roleId=123:owner

With JSONata filter:

epilot permissions putRole -p roleId=123:owner --jsonata '$'

Sample Response

{
  "id": "123:owner",
  "name": "Owner",
  "slug": "owner",
  "type": "user_role",
  "expires_at": "2028-07-21T17:32:28Z",
  "organization_id": "123",
  "grants": [
    {
      "action": "entity-read",
      "resource": "entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947",
      "effect": "allow",
      "conditions": [
        {
          "attribute": "workflows.primary.task_name",
          "operation": "equals",
          "values": ["Qualification"]
        }
      ]
    }
  ],
  "parent_role": "123:owner"
}

---

deleteRole

Delete role by id

DELETE /v1/permissions/roles/{roleId}

Parameters

Name	In	Type	Required	Description
roleId	path	string	Yes

Sample Call

epilot permissions deleteRole \
  -p roleId=123:owner

Using positional args for path parameters:

epilot permissions deleteRole 123:owner

With JSONata filter:

epilot permissions deleteRole -p roleId=123:owner --jsonata '$'

Sample Response

{
  "id": "123:owner",
  "name": "Owner",
  "slug": "owner",
  "type": "user_role",
  "expires_at": "2028-07-21T17:32:28Z",
  "organization_id": "123",
  "grants": [
    {
      "action": "entity-read",
      "resource": "entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947",
      "effect": "allow",
      "conditions": [
        {
          "attribute": "workflows.primary.task_name",
          "operation": "equals",
          "values": ["Qualification"]
        }
      ]
    }
  ],
  "parent_role": "123:owner"
}

---

refreshPermissions

Makes sure the user has a role in the organization

GET /v1/permissions/refresh

Sample Call

epilot permissions refreshPermissions

With JSONata filter:

epilot permissions refreshPermissions --jsonata '$'

---

getAssignedRolesForUser

Get list of assigned roles by user id

GET /v1/permissions/assignments/{userId}

Parameters

Name	In	Type	Required	Description
userId	path	string	Yes

Sample Call

epilot permissions getAssignedRolesForUser \
  -p userId=1

Using positional args for path parameters:

epilot permissions getAssignedRolesForUser 1

With JSONata filter:

epilot permissions getAssignedRolesForUser -p userId=1 --jsonata '$'

Sample Response

["123:owner"]

---

assignRoles

Assign / unassign roles to users.

PUT /v1/permissions/assignments/{userId}

Parameters

Name	In	Type	Required	Description
userId	path	string	Yes

Request Body

Sample Call

epilot permissions assignRoles \
  -p userId=1 \
  -d '["123:owner"]'

Using positional args for path parameters:

epilot permissions assignRoles 1

Using stdin pipe:

cat body.json | epilot permissions assignRoles -p userId=1

With JSONata filter:

epilot permissions assignRoles -p userId=1 --jsonata '$'

Sample Response

["123:owner"]

---

addAssignment

Assign a user to a role.

POST /v1/permissions/assignments/{userId}/{roleId}

Parameters

Name	In	Type	Required	Description
userId	path	string	Yes
roleId	path	string	Yes

Sample Call

epilot permissions addAssignment \
  -p userId=1 \
  -p roleId=123:owner

Using positional args for path parameters:

epilot permissions addAssignment 1 123:owner

With JSONata filter:

epilot permissions addAssignment -p userId=1 -p roleId=123:owner --jsonata 'user_id'

Sample Response

{
  "user_id": "1",
  "roles": ["123:owner"]
}

---

removeAssignment

Remove role assignment from user

DELETE /v1/permissions/assignments/{userId}/{roleId}

Parameters

Name	In	Type	Required	Description
userId	path	string	Yes
roleId	path	string	Yes

Sample Call

epilot permissions removeAssignment \
  -p userId=1 \
  -p roleId=123:owner

Using positional args for path parameters:

epilot permissions removeAssignment 1 123:owner

With JSONata filter:

epilot permissions removeAssignment -p userId=1 -p roleId=123:owner --jsonata 'user_id'

Sample Response

{
  "user_id": "1",
  "roles": ["123:owner"]
}

---

listAllAssignments

Returns list of all assignments in organization

GET /v1/permissions/assignments

Sample Call

epilot permissions listAllAssignments

With JSONata filter:

epilot permissions listAllAssignments --jsonata 'assignments'

Sample Response

{
  "assignments": [
    {
      "user_id": "1",
      "roles": ["123:owner"]
    }
  ]
}

---