From 03e03b5af3f29571f95cb757f93bb24894901b84 Mon Sep 17 00:00:00 2001 From: Ernesto Resende Date: Thu, 19 Mar 2026 17:04:12 +0000 Subject: [PATCH] docs(sdk): update partner directory sdk docs --- docs/sdk/clients/partner-directory.md | 424 ++++++++++++++++++-------- 1 file changed, 296 insertions(+), 128 deletions(-) diff --git a/docs/sdk/clients/partner-directory.md b/docs/sdk/clients/partner-directory.md index 1f1b484..f793039 100644 --- a/docs/sdk/clients/partner-directory.md +++ b/docs/sdk/clients/partner-directory.md @@ -1,8 +1,8 @@ --- -title: "Partner API" +title: "Partner Directory API" --- -# Partner API +# Partner Directory API - **Base URL:** `https://partner-directory-api.sls.epilot.io` - **Full API Docs:** [https://docs.epilot.io/api/partner-directory](https://docs.epilot.io/api/partner-directory) @@ -28,7 +28,7 @@ const { data } = await partnerDirectoryClient.approvePartner(...) ## Operations -**partners** +**Partners** - [`approvePartner`](#approvepartner) - [`rejectPartner`](#rejectpartner) - [`searchAssignable`](#searchassignable) @@ -38,13 +38,14 @@ const { data } = await partnerDirectoryClient.approvePartner(...) - [`searchGeolocationForText`](#searchgeolocationfortext) - [`invitePartnerV2`](#invitepartnerv2) -**partner_users** +**Partner Users** - [`getPartnerUsers`](#getpartnerusers) - [`createPartnerUser`](#createpartneruser) - [`deletePartnerUser`](#deletepartneruser) - [`getPartnerRoles`](#getpartnerroles) - [`createPartnerRole`](#createpartnerrole) - [`updatePartnerRole`](#updatepartnerrole) +- [`deletePartnerRole`](#deletepartnerrole) - [`assignPartnerUserRoles`](#assignpartneruserroles) - [`unassignPartnerUserRoles`](#unassignpartneruserroles) @@ -82,7 +83,7 @@ const { data } = await partnerDirectoryClient.approvePartner(...) ### `approvePartner` -Approve partner request +Approves a pending partner request, allowing the partner to begin collaboration. `POST /v1/partners/{id}/approve` @@ -100,14 +101,14 @@ const { data } = await client.approvePartner({ "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc", "organization_id": "123", "created_at": "2022-02-08T04:44:32.246Z", - "description": "Description", - "company_name": "Company name", - "invitation_token": "string", + "description": "Regional solar installation partner for Bavaria", + "company_name": "Acme Solar GmbH", + "invitation_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "invitation_email": "user@example.com", - "email": "user@example.com", - "owner_email": "user@example.com", - "signed_up_email": "user@example.com", - "partner_org_id": 123456, + "email": "contact@acme-solar.de", + "owner_email": "owner@acme-solar.de", + "signed_up_email": "admin@acme-solar.de", + "partner_org_id": "456789", "status": "Pending" } ``` @@ -118,7 +119,7 @@ const { data } = await client.approvePartner({ ### `rejectPartner` -Reject partner request +Rejects a pending partner request, declining the partnership. `POST /v1/partners/{id}/reject` @@ -136,14 +137,14 @@ const { data } = await client.rejectPartner({ "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc", "organization_id": "123", "created_at": "2022-02-08T04:44:32.246Z", - "description": "Description", - "company_name": "Company name", - "invitation_token": "string", + "description": "Regional solar installation partner for Bavaria", + "company_name": "Acme Solar GmbH", + "invitation_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "invitation_email": "user@example.com", - "email": "user@example.com", - "owner_email": "user@example.com", - "signed_up_email": "user@example.com", - "partner_org_id": 123456, + "email": "contact@acme-solar.de", + "owner_email": "owner@acme-solar.de", + "signed_up_email": "admin@acme-solar.de", + "partner_org_id": "456789", "status": "Pending" } ``` @@ -154,7 +155,7 @@ const { data } = await client.rejectPartner({ ### `searchAssignable` -searchAssignables +Search for users and organizations that can be assigned to tasks, workflows, or entities. `POST /v1/partners/assignables:search` @@ -162,11 +163,11 @@ searchAssignables const { data } = await client.searchAssignable( null, { - q: '', + q: 'john', from: 0, size: 25, - org_ids: ['123'], - portalUsersEntityIdScope: '', + org_ids: ['123', '456'], + portalUsersEntityIdScope: 'f7c22299-ca72-4bca-8538-0a88eeefc947', types: ['user', 'partner_user', 'partner_organization', 'ecp', 'group'] }, ) @@ -177,11 +178,11 @@ const { data } = await client.searchAssignable( ```json { - "hits": 25, + "hits": 42, "results": [ { "type": "user", - "display_name": "Example User", + "display_name": "John Smith", "image_uri": { "original": "https://epilot-staging-user-content.s3.eu-central-1.amazonaws.com/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png", "thumbnail_32": "https://file.sls.epilot.io/v1/files/public/preview?w=32&h=32&key=/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png" @@ -191,7 +192,7 @@ const { data } = await client.searchAssignable( "activated_at": "2022-02-08T04:44:32.246Z", "status": "Active", "user_id": "456", - "email": "example@example.com" + "email": "john.smith@example.com" } ] } @@ -203,7 +204,7 @@ const { data } = await client.searchAssignable( ### `batchGetAssignable` -batchGet +Retrieve multiple assignable users or groups by their IDs in a single request. `POST /v1/partners/assignables:batchGet` @@ -212,9 +213,9 @@ const { data } = await client.batchGetAssignable( null, [ { - user_id: 'string', - org_id: 'string', - group_id: 'string' + user_id: '456', + org_id: '123', + group_id: 'group-789' } ], ) @@ -225,11 +226,11 @@ const { data } = await client.batchGetAssignable( ```json { - "hits": 25, + "hits": 3, "results": [ { "type": "user", - "display_name": "Example User", + "display_name": "John Smith", "image_uri": { "original": "https://epilot-staging-user-content.s3.eu-central-1.amazonaws.com/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png", "thumbnail_32": "https://file.sls.epilot.io/v1/files/public/preview?w=32&h=32&key=/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png" @@ -239,7 +240,7 @@ const { data } = await client.batchGetAssignable( "activated_at": "2022-02-08T04:44:32.246Z", "status": "Active", "user_id": "456", - "email": "example@example.com" + "email": "john.smith@example.com" } ] } @@ -251,7 +252,7 @@ const { data } = await client.batchGetAssignable( ### `getPartnerByToken` -Get partner by token +Retrieves partner information using an invitation token. `GET /v1/partner-directory/public/getPartnerByToken` @@ -269,14 +270,14 @@ const { data } = await client.getPartnerByToken({ "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc", "organization_id": "123", "created_at": "2022-02-08T04:44:32.246Z", - "description": "Description", - "company_name": "Company name", - "invitation_token": "string", + "description": "Regional solar installation partner for Bavaria", + "company_name": "Acme Solar GmbH", + "invitation_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "invitation_email": "user@example.com", - "email": "user@example.com", - "owner_email": "user@example.com", - "signed_up_email": "user@example.com", - "partner_org_id": 123456, + "email": "contact@acme-solar.de", + "owner_email": "owner@acme-solar.de", + "signed_up_email": "admin@acme-solar.de", + "partner_org_id": "456789", "status": "Pending" } ``` @@ -287,7 +288,7 @@ const { data } = await client.getPartnerByToken({ ### `activatePartner` -Activate partner using an invite token +Activates a partner account using an invitation token. `POST /v1/partner-directory/public/activate` @@ -297,9 +298,9 @@ const { data } = await client.activatePartner( token: 'example', }, { - company_name: 'Company name', - signed_up_email: 'user@example.com', - organization_id: 'string' + company_name: 'Acme Solar GmbH', + signed_up_email: 'admin@acme-solar.de', + organization_id: '456' }, ) ``` @@ -308,7 +309,7 @@ const { data } = await client.activatePartner( ### `searchGeolocationForText` -Converts a given string, in the format of an address, to geo-location latitude and longitude +Converts an address string to geographic coordinates (latitude and longitude). `POST /v1/geolocation/text:search` @@ -328,8 +329,8 @@ const { data } = await client.searchGeolocationForText( { "lat": 49.013, "lng": 12.101, - "addressLabel": "string", - "relevance": 0 + "addressLabel": "Auweg 1, 93055 Regensburg, Germany", + "relevance": 0.95 } ``` @@ -339,7 +340,7 @@ const { data } = await client.searchGeolocationForText( ### `invitePartnerV2` -Invite a partner into collaboration. It will send an email to partner and ask to join into collaboration +Sends an invitation email to a partner organization to begin collaboration. `POST /v2/partners/{id}/invite` @@ -349,7 +350,7 @@ const { data } = await client.invitePartnerV2( id: '123e4567-e89b-12d3-a456-426614174000', }, { - language: 'en' + language: 'de' }, ) ``` @@ -362,14 +363,14 @@ const { data } = await client.invitePartnerV2( "id": "e45a6dc2-3795-43a3-ae0f-6b6760f310fc", "organization_id": "123", "created_at": "2022-02-08T04:44:32.246Z", - "description": "Description", - "company_name": "Company name", - "invitation_token": "string", + "description": "Regional solar installation partner for Bavaria", + "company_name": "Acme Solar GmbH", + "invitation_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "invitation_email": "user@example.com", - "email": "user@example.com", - "owner_email": "user@example.com", - "signed_up_email": "user@example.com", - "partner_org_id": 123456, + "email": "contact@acme-solar.de", + "owner_email": "owner@acme-solar.de", + "signed_up_email": "admin@acme-solar.de", + "partner_org_id": "456789", "status": "Pending" } ``` @@ -380,7 +381,7 @@ const { data } = await client.invitePartnerV2( ### `getPartnerUsers` -Get all users for a partner organization with their roles +Retrieves all users belonging to a partner organization along with their assigned roles. `GET /v2/partners/{orgId}/users` @@ -399,7 +400,7 @@ const { data } = await client.getPartnerUsers({ { "id": "456", "name": "John Doe", - "email": "user@example.com", + "email": "user@partner.com", "status": "Active", "image": { "original": "https://example.com/path", @@ -407,9 +408,9 @@ const { data } = await client.getPartnerUsers({ }, "roles": [ { - "id": "role-123", - "slug": "admin", - "name": "Administrator" + "id": "123:partner_admin", + "slug": "partner_admin", + "name": "Partner Administrator" } ] } @@ -423,7 +424,7 @@ const { data } = await client.getPartnerUsers({ ### `createPartnerUser` -Create a new user in a partner organization +Creates a new user in a partner organization. `POST /v2/partners/{orgId}/users` @@ -433,9 +434,9 @@ const { data } = await client.createPartnerUser( orgId: 'example', }, { - email: 'user@example.com', - language: 'en', - roles: ['role-123', 'role-456'] + email: 'newuser@partner.com', + language: 'de', + roles: ['123:partner_viewer'] }, ) ``` @@ -458,7 +459,7 @@ const { data } = await client.createPartnerUser( ### `deletePartnerUser` -Delete a user from a partner organization +Removes a user from a partner organization. `DELETE /v2/partners/{orgId}/users/{userId}` @@ -482,7 +483,7 @@ const { data } = await client.deletePartnerUser({ ### `getPartnerRoles` -Get all roles for a partner organization +Retrieves all roles defined for a partner organization. `GET /v2/partners/{orgId}/roles` @@ -499,10 +500,24 @@ const { data } = await client.getPartnerRoles({ { "results": [ { - "id": "role-123", - "slug": "admin", - "name": "Administrator", - "type": "share_role" + "id": "123:partner_admin", + "slug": "partner_admin", + "name": "Partner Administrator", + "type": "share_role", + "grants": [ + { + "action": "entity-read", + "resource": "entity:123:contact:*", + "effect": "allow", + "conditions": [ + { + "attribute": "workflows.primary.task_name", + "operation": "equals", + "values": ["Qualification"] + } + ] + } + ] } ] } @@ -514,7 +529,7 @@ const { data } = await client.getPartnerRoles({ ### `createPartnerRole` -Create a role for a partner organization +Creates a new role for a partner organization. `POST /v2/partners/{orgId}/roles` @@ -524,12 +539,12 @@ const { data } = await client.createPartnerRole( orgId: 'example', }, { - name: 'Partner Admin', + name: 'Partner Administrator', slug: 'partner_admin', grants: [ { action: 'entity-read', - resource: 'entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947', + resource: 'entity:123:contact:*', effect: 'allow', conditions: [ { @@ -541,7 +556,7 @@ const { data } = await client.createPartnerRole( dependencies: [ { action: 'entity-read', - resource: 'entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947', + resource: 'entity:123:contact:*', effect: 'allow', conditions: [ { @@ -563,10 +578,24 @@ const { data } = await client.createPartnerRole( ```json { - "id": "role-123", - "slug": "admin", - "name": "Administrator", - "type": "share_role" + "id": "123:partner_admin", + "slug": "partner_admin", + "name": "Partner Administrator", + "type": "share_role", + "grants": [ + { + "action": "entity-read", + "resource": "entity:123:contact:*", + "effect": "allow", + "conditions": [ + { + "attribute": "workflows.primary.task_name", + "operation": "equals", + "values": ["Qualification"] + } + ] + } + ] } ``` @@ -576,7 +605,7 @@ const { data } = await client.createPartnerRole( ### `updatePartnerRole` -Update a role for a partner organization +Updates an existing role in a partner organization. `PUT /v2/partners/{orgId}/roles/{roleId}` @@ -590,7 +619,7 @@ const { data } = await client.updatePartnerRole( grants: [ { action: 'entity-read', - resource: 'entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947', + resource: 'entity:123:contact:*', effect: 'allow', conditions: [ { @@ -602,7 +631,7 @@ const { data } = await client.updatePartnerRole( dependencies: [ { action: 'entity-read', - resource: 'entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947', + resource: 'entity:123:contact:*', effect: 'allow', conditions: [ { @@ -627,10 +656,67 @@ const { data } = await client.updatePartnerRole( ```json { - "id": "role-123", - "slug": "admin", - "name": "Administrator", - "type": "share_role" + "id": "123:partner_admin", + "slug": "partner_admin", + "name": "Partner Administrator", + "type": "share_role", + "grants": [ + { + "action": "entity-read", + "resource": "entity:123:contact:*", + "effect": "allow", + "conditions": [ + { + "attribute": "workflows.primary.task_name", + "operation": "equals", + "values": ["Qualification"] + } + ] + } + ] +} +``` + + + +--- + +### `deletePartnerRole` + +Delete a role from a partner organization + +`DELETE /v2/partners/{orgId}/roles/{roleId}` + +```ts +const { data } = await client.deletePartnerRole({ + orgId: 'example', + roleId: 'example', +}) +``` + +
+Response + +```json +{ + "id": "123:partner_admin", + "slug": "partner_admin", + "name": "Partner Administrator", + "type": "share_role", + "grants": [ + { + "action": "entity-read", + "resource": "entity:123:contact:*", + "effect": "allow", + "conditions": [ + { + "attribute": "workflows.primary.task_name", + "operation": "equals", + "values": ["Qualification"] + } + ] + } + ] } ``` @@ -640,7 +726,7 @@ const { data } = await client.updatePartnerRole( ### `assignPartnerUserRoles` -Assign roles to a user in a partner organization +Assigns one or more roles to a user in a partner organization. `POST /v2/partners/{orgId}/users/{userId}/roles` @@ -651,7 +737,7 @@ const { data } = await client.assignPartnerUserRoles( userId: 'example', }, { - roleIds: ['role-123', 'role-456'] + roleIds: ['123:partner_admin', '123:partner_viewer'] }, ) ``` @@ -678,7 +764,7 @@ const { data } = await client.assignPartnerUserRoles( ### `unassignPartnerUserRoles` -Unassign roles from a user in a partner organization +Removes one or more roles from a user in a partner organization. `DELETE /v2/partners/{orgId}/users/{userId}/roles` @@ -689,7 +775,7 @@ const { data } = await client.unassignPartnerUserRoles( userId: 'example', }, { - roleIds: ['role-123', 'role-456'] + roleIds: ['123:partner_admin', '123:partner_viewer'] }, ) ``` @@ -718,17 +804,26 @@ const { data } = await client.unassignPartnerUserRoles( ### `InviteToken` +A secure token used for partner invitation and activation. Sent via email to the invited partner. + ```ts type InviteToken = string ``` ### `Partner` +Represents a partner organization in the partner directory. + +Partners go through a lifecycle from invitation to active collaboration: +- **Pending**: Initial state when partner record is created +- **Invited**: Invitation email has been sent to the partner +- **Request**: Partner has requested to join + ```ts type Partner = { id?: string organization_id?: string - created_at?: string + created_at?: string // date-time description?: string company_name?: string invitation_token?: string @@ -743,18 +838,24 @@ type Partner = { ### `PartnerId` +Unique identifier for a partner record (UUID format) + ```ts type PartnerId = string ``` ### `OrganizationId` +Unique identifier for an organization in the epilot platform + ```ts type OrganizationId = string ``` ### `ActivatePartnerPayload` +Payload for activating a partner account using an invitation token + ```ts type ActivatePartnerPayload = { company_name?: string @@ -765,6 +866,8 @@ type ActivatePartnerPayload = { ### `PartnerInvitationPayload` +Configuration options for sending a partner invitation + ```ts type PartnerInvitationPayload = { language?: "en" | "de" @@ -773,6 +876,10 @@ type PartnerInvitationPayload = { ### `Assignable` +A user, organization, or group that can be assigned to tasks, workflows, or entities. +The `type` field discriminates between different assignable types. + + ```ts type Assignable = { type: "user" @@ -782,11 +889,11 @@ type Assignable = { thumbnail_32?: string // uri } org_id: string - created_at?: string - activated_at?: string + created_at?: string // date-time + activated_at?: string // date-time status?: "Active" | "Pending" | "Deactivated" | "Deleted" user_id?: string - email?: string + email?: string // email } | { type: "partner_user" display_name: string @@ -795,12 +902,12 @@ type Assignable = { thumbnail_32?: string // uri } org_id: string - created_at?: string - activated_at?: string + created_at?: string // date-time + activated_at?: string // date-time status?: "Active" | "Pending" | "Deactivated" | "Deleted" partner_id?: string user_id?: string - email?: string + email?: string // email } | { type: "partner_organization" display_name: string @@ -809,11 +916,11 @@ type Assignable = { thumbnail_32?: string // uri } org_id: string - created_at?: string - activated_at?: string + created_at?: string // date-time + activated_at?: string // date-time status?: "Active" | "Pending" | "Deactivated" | "Deleted" partner_id: string - email?: string + email?: string // email geolocations?: Array<{ address?: { street?: { ... } @@ -837,21 +944,21 @@ type Assignable = { thumbnail_32?: string // uri } org_id: string - created_at?: string - activated_at?: string + created_at?: string // date-time + activated_at?: string // date-time status?: "Active" | "Pending" | "Deactivated" | "Deleted" user_id: string - email?: string + email?: string // email } | { - type: string + type: "group" display_name: string image_uri?: { original: string // uri thumbnail_32?: string // uri } org_id: string - created_at?: string - activated_at?: string + created_at?: string // date-time + activated_at?: string // date-time status?: "Active" | "Pending" | "Deactivated" | "Deleted" group_id?: string } @@ -859,6 +966,8 @@ type Assignable = { ### `BaseAssignable` +Common properties shared by all assignable types + ```ts type BaseAssignable = { type: string @@ -868,14 +977,16 @@ type BaseAssignable = { thumbnail_32?: string // uri } org_id: string - created_at?: string - activated_at?: string + created_at?: string // date-time + activated_at?: string // date-time status?: "Active" | "Pending" | "Deactivated" | "Deleted" } ``` ### `AssignableUser` +A user within the caller's organization that can be assigned to tasks or entities + ```ts type AssignableUser = { type: "user" @@ -885,16 +996,18 @@ type AssignableUser = { thumbnail_32?: string // uri } org_id: string - created_at?: string - activated_at?: string + created_at?: string // date-time + activated_at?: string // date-time status?: "Active" | "Pending" | "Deactivated" | "Deleted" user_id?: string - email?: string + email?: string // email } ``` ### `AssignablePartnerUser` +A user from a partner organization that can be assigned to shared tasks or entities + ```ts type AssignablePartnerUser = { type: "partner_user" @@ -904,28 +1017,30 @@ type AssignablePartnerUser = { thumbnail_32?: string // uri } org_id: string - created_at?: string - activated_at?: string + created_at?: string // date-time + activated_at?: string // date-time status?: "Active" | "Pending" | "Deactivated" | "Deleted" partner_id?: string user_id?: string - email?: string + email?: string // email } ``` ### `AssignableGroup` +A user group that can be assigned to tasks or entities. All members of the group will be notified/assigned. + ```ts type AssignableGroup = { - type: string + type: "group" display_name: string image_uri?: { original: string // uri thumbnail_32?: string // uri } org_id: string - created_at?: string - activated_at?: string + created_at?: string // date-time + activated_at?: string // date-time status?: "Active" | "Pending" | "Deactivated" | "Deleted" group_id?: string } @@ -933,6 +1048,10 @@ type AssignableGroup = { ### `AssignableOrganization` +A partner organization that can be assigned to tasks or entities at the organization level. +Useful when you want to assign work to a partner company rather than a specific individual. + + ```ts type AssignableOrganization = { type: "partner_organization" @@ -942,11 +1061,11 @@ type AssignableOrganization = { thumbnail_32?: string // uri } org_id: string - created_at?: string - activated_at?: string + created_at?: string // date-time + activated_at?: string // date-time status?: "Active" | "Pending" | "Deactivated" | "Deleted" partner_id: string - email?: string + email?: string // email geolocations?: Array<{ address?: { street?: { ... } @@ -967,6 +1086,10 @@ type AssignableOrganization = { ### `AssignableEcpPlaceholder` +An End Customer Portal (ECP) user that can be assigned to tasks or entities. +These are external users who access the system through the customer portal. + + ```ts type AssignableEcpPlaceholder = { type: "ecp" @@ -976,16 +1099,18 @@ type AssignableEcpPlaceholder = { thumbnail_32?: string // uri } org_id: string - created_at?: string - activated_at?: string + created_at?: string // date-time + activated_at?: string // date-time status?: "Active" | "Pending" | "Deactivated" | "Deleted" user_id: string - email?: string + email?: string // email } ``` ### `SearchGeolocation` +Request payload for geocoding an address to coordinates + ```ts type SearchGeolocation = { address: string @@ -994,6 +1119,8 @@ type SearchGeolocation = { ### `Geolocation` +Geographic coordinates with optional metadata + ```ts type Geolocation = { lat: number @@ -1005,6 +1132,8 @@ type Geolocation = { ### `Address` +Structured postal address + ```ts type Address = { street?: string @@ -1017,6 +1146,8 @@ type Address = { ### `AddressGeolocation` +Combined address and geographic coordinates for a location + ```ts type AddressGeolocation = { address?: { @@ -1035,6 +1166,8 @@ type AddressGeolocation = { ### `PartnerUser` +A user within a partner organization, including their assigned roles + ```ts type PartnerUser = { id: string @@ -1055,6 +1188,8 @@ type PartnerUser = { ### `CreatePartnerUserPayload` +Request payload for creating a new user in a partner organization + ```ts type CreatePartnerUserPayload = { email: string // email @@ -1065,6 +1200,8 @@ type CreatePartnerUserPayload = { ### `CreatePartnerRolePayload` +Request payload for creating a new role in a partner organization + ```ts type CreatePartnerRolePayload = { name: string @@ -1086,6 +1223,8 @@ type CreatePartnerRolePayload = { ### `UpdatePartnerRolePayload` +Request payload for updating an existing role in a partner organization + ```ts type UpdatePartnerRolePayload = { grants: Array<{ @@ -1102,6 +1241,11 @@ type UpdatePartnerRolePayload = { ### `Grant` +A permission grant that allows or denies a specific action on a resource. + +Grants are the building blocks of roles and define what users can do within the system. + + ```ts type Grant = { action: string @@ -1113,6 +1257,8 @@ type Grant = { ### `GrantWithDependencies` +A grant with optional dependent grants that are automatically included when this grant is assigned + ```ts type GrantWithDependencies = { action: string @@ -1130,32 +1276,42 @@ type GrantWithDependencies = { ### `GrantCondition` +An additional condition that must be met for a grant to apply. +Conditions allow fine-grained control over when permissions are active. + + ```ts type GrantCondition = object ``` ### `EqualsCondition` -Check if attribute equals to any of the values +A condition that checks if an attribute equals one of the specified values. +The grant only applies when the condition is satisfied. + ```ts type EqualsCondition = { attribute: string operation: "equals" - values: unknown[] + values: string[] } ``` ### `RoleId` +Unique identifier for a role, combining organization ID and role slug. Format: ``:`` + ```ts type RoleId = string ``` ### `BaseRoleForCreate` +Base schema for creating or updating a role + ```ts type BaseRoleForCreate = { id?: string @@ -1172,17 +1328,27 @@ type BaseRoleForCreate = { ### `PartnerRole` +A role definition for users in a partner organization + ```ts type PartnerRole = { id: string slug: string name: string type?: string + grants: Array<{ + action: string + resource?: string + effect?: "allow" | "deny" + conditions?: object[] + }> } ``` ### `AssignRolesPayload` +Request payload for assigning or unassigning roles to/from a user + ```ts type AssignRolesPayload = { roleIds: string[] @@ -1191,11 +1357,13 @@ type AssignRolesPayload = { ### `User` +A user account in the epilot platform + ```ts type User = { id?: string email?: string // email display_name?: string - status?: string + status?: "Active" | "Pending" | "Deactivated" } ```