Companies & Roles — Overview
A role groups together a set of permissions and is assigned to one or more users of the company. The permissions themselves — what each action, on each module, allows — form a common catalog for the platform, queryable separately.
Endpoints in this domain
| Method | Path | Description |
|---|---|---|
GET | /v1/companies/{id}/users | Lists a company's users |
GET | /v1/companies/{companyId}/roles | Lists a company's roles |
PUT | /v1/companies/roles/{roleId} | Updates a role (full replacement) |
GET | /v1/companies/users/permissions | Lists the catalog of available permissions |
POST | /v1/companies/roles | Creates a new role |
GET | /v1/companies/{id}/logo-upload-url | Generates a company logo upload URL |
GET | /v1/companies/{id}/logo-download-url | Generates a company logo download URL |
PATCH | {baseUrlRole}/v2/users/{userId}/agflow-role | Assigns roles to a user |
Alternate base URL particularity: the endpoint for assigning roles to a user ( PATCH {baseUrlRole}/v2/users/{userId}/agflow-role) does not serve on the same base URL as the other endpoints in this domain — nor as the other AgFlow API domains. It uses a distinct base URL, dedicated to user identity/role operations. When integrating, you must configure the appropriate base URL for this specific operation; using the standard AgFlow API base here results in a connection failure or a non-existent route.
Role × permissions
name, description, type, intern) plus a permissions list, in the format [{module, permissions: {<resource>: [actions]}}]. Each module (for example, card, credit, flow, documents) groups resources, and each resource lists the allowed actions (view, create, update, delete, move, among others, varying by resource). The complete catalog of modules, resources, and available actions can be browsed through the permissions listing endpoint.Important behaviors
PUT /v1/companies/roles/{roleId}) is a full replacement of the object — there is no partial update and no prior read of individual permissions by the API. The complete desired data set must be resent on every update, even when only one field is changing.GET /v1/companies/{companyId}/roles) returns only basic identification (id, name, description) — never the permissions array. Since there is no way to read a role's current permissions through this or any other endpoint, we recommend keeping that state on the integration side.global query parameter is sent as true.POST /v1/companies/roles), only the name field is required — the other fields are optional, but we recommend always sending them complete, since a future update will be a full replacement.GET /v1/companies/{id}/users) expects the organization identifier in the path — an identifier in a different format than expected returns a server-side error (502).PATCH {baseUrlRole}/v2/users/{userId}/agflow-role) fully replaces the user's role list — it does not merge. To add a role without removing the ones already assigned, you must resend the complete list (existing roles plus the new one).Modificado em 2026-07-28 20:38:32