Skip to main content

Permissions API

Usage​

import { epilot } from '@epilot/sdk'

epilot.authorize(() => '<token>')
const { data } = await epilot.permissions.listCurrentRoles(...)

Tree-shakeable import​

import { getClient, authorize } from '@epilot/sdk/permissions'

const permissionsClient = getClient()
authorize(permissionsClient, () => '<token>')
const { data } = await permissionsClient.listCurrentRoles(...)

Operations​

Roles

Assignments

Schemas

listCurrentRoles​

Returns roles and grants assigned to current user

GET /v1/permissions/me

const { data } = await client.listCurrentRoles()
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

const { data } = await client.listAllRoles()
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

const { data } = await client.createRole(
  null,
  {},
)
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

const { data } = await client.searchRoles(
  null,
  {
    role_ids: ['123:manager', '456:owner'],
    org_ids: ['123', '456'],
    slugs: ['manager', 'owner'],
    query: 'Administrator',
    limit: 1,
    offset: 1
  },
)
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}

const { data } = await client.getRole({
  roleId: 'example',
})
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}

const { data } = await client.putRole(
  {
    roleId: 'example',
  },
  {
    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'
  },
)
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}

const { data } = await client.deleteRole({
  roleId: 'example',
})
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

const { data } = await client.refreshPermissions()

getAssignedRolesForUser​

Get list of assigned roles by user id

GET /v1/permissions/assignments/{userId}

const { data } = await client.getAssignedRolesForUser({
  userId: 'example',
})
Response
["123:owner"]

assignRoles​

Assign / unassign roles to users.

PUT /v1/permissions/assignments/{userId}

const { data } = await client.assignRoles(
  {
    userId: 'example',
  },
  ['123:owner'],
)
Response
["123:owner"]

addAssignment​

Assign a user to a role.

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

const { data } = await client.addAssignment({
  userId: 'example',
  roleId: 'example',
})
Response
{
  "user_id": "1",
  "roles": ["123:owner"]
}

removeAssignment​

Remove role assignment from user

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

const { data } = await client.removeAssignment({
  userId: 'example',
  roleId: 'example',
})
Response
{
  "user_id": "1",
  "roles": ["123:owner"]
}

listAllAssignments​

Returns list of all assignments in organization

GET /v1/permissions/assignments

const { data } = await client.listAllAssignments()
Response
{
  "assignments": [
    {
      "user_id": "1",
      "roles": ["123:owner"]
    }
  ]
}

Schemas​

Grant​

type Grant = {
  action: string
  resource?: string
  effect?: "allow" | "deny"
  conditions?: object[]
}

GrantWithDependencies​

type GrantWithDependencies = {
  action: string
  resource?: string
  effect?: "allow" | "deny"
  conditions?: object[]
  dependencies?: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
}

GrantCondition​

type GrantCondition = object

EqualsCondition​

Check if attribute equals to any of the values

type EqualsCondition = {
  attribute: string
  operation: "equals"
  values: unknown[]
}

RoleId​

Format: <organization_id>:<slug>

type RoleId = string

BaseRole​

type BaseRole = {
  id: string
  name: string
  slug: string
  type: string
  expires_at?: string // date-time
  organization_id: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
}

BaseRoleForCreate​

type BaseRoleForCreate = {
  id?: string
  name: string
  slug: string
  type: string
  expires_at?: string // date-time
  organization_id?: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
}

UserRole​

type UserRole = {
  id: string
  name: string
  slug: string
  type: "user_role"
  expires_at?: string // date-time
  organization_id: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
  parent_role?: object
}

OrgRole​

type OrgRole = {
  id: string
  name: string
  slug: string
  type: "org_role"
  expires_at?: string // date-time
  organization_id: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
  pricing_tier?: string
}

ShareRole​

type ShareRole = {
  id: string
  name: string
  slug: string
  type: "share_role"
  expires_at?: string // date-time
  organization_id: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
}

PartnerRole​

type PartnerRole = {
  id: string
  name: string
  slug: string
  type: "partner_role"
  expires_at?: string // date-time
  organization_id: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
  partner_org_id?: object
  vendor_enforced_user_limit?: number
}

PortalRole​

type PortalRole = {
  id: string
  name: string
  slug: string
  type: "portal_role"
  expires_at?: string // date-time
  organization_id: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
}

Role​

type Role = {
  id: string
  name: string
  slug: string
  type: "user_role"
  expires_at?: string // date-time
  organization_id: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
  parent_role?: object
} | {
  id: string
  name: string
  slug: string
  type: "org_role"
  expires_at?: string // date-time
  organization_id: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
  pricing_tier?: string
} | {
  id: string
  name: string
  slug: string
  type: "share_role"
  expires_at?: string // date-time
  organization_id: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
} | {
  id: string
  name: string
  slug: string
  type: "partner_role"
  expires_at?: string // date-time
  organization_id: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
  partner_org_id?: object
  vendor_enforced_user_limit?: number
} | {
  id: string
  name: string
  slug: string
  type: "portal_role"
  expires_at?: string // date-time
  organization_id: string
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
}

RolePayload​

type RolePayload = {
  grants?: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
    dependencies?: Array<{
      action: { ... }
      resource?: { ... }
      effect?: { ... }
      conditions?: { ... }
    }>
  }>
}

Assignment​

A role attached to an user

type Assignment = {
  user_id?: string
  roles?: string[]
}

InternalAssignment​

A role attached to an user

type InternalAssignment = {
  userId?: string
  roles?: string[]
}

OrgAssignments​

All roles attached to an users of an organization

type OrgAssignments = {
  organizationId?: string
  assignments?: Array<{
    userId?: string
    roles?: string[]
  }>
}

OrgRoles​

All roles attached to an users of an organization

type OrgRoles = {
  organizationId?: string
  roles?: Array<{
    id: string
    name: string
    slug: string
    type: "user_role"
    expires_at?: string // date-time
    organization_id: string
    grants: Array<{
      action: { ... }
      resource?: { ... }
      effect?: { ... }
      conditions?: { ... }
    }>
    parent_role?: object
  } | {
    id: string
    name: string
    slug: string
    type: "org_role"
    expires_at?: string // date-time
    organization_id: string
    grants: Array<{
      action: { ... }
      resource?: { ... }
      effect?: { ... }
      conditions?: { ... }
    }>
    pricing_tier?: string
  } | {
    id: string
    name: string
    slug: string
    type: "share_role"
    expires_at?: string // date-time
    organization_id: string
    grants: Array<{
      action: { ... }
      resource?: { ... }
      effect?: { ... }
      conditions?: { ... }
    }>
  } | {
    id: string
    name: string
    slug: string
    type: "partner_role"
    expires_at?: string // date-time
    organization_id: string
    grants: Array<{
      action: { ... }
      resource?: { ... }
      effect?: { ... }
      conditions?: { ... }
    }>
    partner_org_id?: object
    vendor_enforced_user_limit?: number
  } | {
    id: string
    name: string
    slug: string
    type: "portal_role"
    expires_at?: string // date-time
    organization_id: string
    grants: Array<{
      action: { ... }
      resource?: { ... }
      effect?: { ... }
      conditions?: { ... }
    }>
  }>
}

Assignments​

List of role ids attached to an user

type Assignments = string[]

UserId​

Id of a user

type UserId = string

OrganizationId​

Id of an organization

type OrganizationId = string

Slug​

Slug of a role; for a role with id = 123:manager -> 123 is org_id & manager is slug

type Slug = string

RoleSearchInput​

type RoleSearchInput = {
  role_ids?: string[]
  org_ids?: string[]
  slugs?: string[]
  query?: string
  limit?: number
  offset?: number
}

CreateRolePayload​

type CreateRolePayload = {
  grants: Array<{
    action: string
    resource?: string
    effect?: "allow" | "deny"
    conditions?: object[]
  }>
  id?: string
  name: string
  slug: string
  type: string
  expires_at?: string // date-time
  organization_id?: string
}

Error​

Error response

type Error = {
  message: string
}