IAM

Method	Path	Description
POST	`/api/v1/iam/{workspace}/roles/{roleId}/assignees/{userId}`	Assign role to user
DELETE	`/api/v1/iam/{workspace}/roles/{roleId}/assignees/{userId}`	Remove role from user
POST	`/api/v1/iam/{workspace}/roles/{roleId}/assignees/principals/{principalId}`	Assign role to principal
DELETE	`/api/v1/iam/{workspace}/roles/{roleId}/assignees/principals/{principalId}`	Remove role from principal
GET	`/api/v1/iam/{workspace}/users`	List workspace users
GET	`/api/v1/iam/{workspace}/users/{userId}`	Get workspace user
GET	`/api/v1/iam/{workspace}/users/{userId}/roles`	Get user roles in workspace
GET	`/api/v1/iam/{workspace}/users/me/principal`	Get current user's principal
GET	`/api/v1/iam/{workspace}/roles`	List roles in workspace
GET	`/api/v1/iam/{workspace}/roles/{roleId}`	Get role by ID
GET	`/api/v1/iam/{workspace}/roles/{roleId}/assignees`	List role assignees
GET	`/api/v1/iam/{workspace}/agents`	List agents in workspace
GET	`/api/v1/iam/{workspace}/agents/{agentId}`	Get agent by ID
GET	`/api/v1/iam/{workspace}/agents/{agentId}/roles`	List agent roles

Assign role to user

POST /api/v1/iam/{workspace}/roles/{roleId}/assignees/{userId}

Assign a role to a user

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`roleId`	Yes	Role ID
`userId`	Yes	User ID

Responses

Status	Description
`200`	Role assigned successfully
`404`	Role or user not found
`409`	User already has this role

Example Response

{
  "success": true,
  "data": "string"
}

Example

curl -X POST "https://poliglot.io/api/v1/iam/my-workspace/roles/<roleId>/assignees/<userId>" \
  -H "Authorization: Bearer <your-token>"

Remove role from user

DELETE /api/v1/iam/{workspace}/roles/{roleId}/assignees/{userId}

Remove a role assignment from a user

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`roleId`	Yes	Role ID
`userId`	Yes	User ID

Responses

Status	Description
`200`	Role assignment removed successfully
`404`	Role, user, or assignment not found

Example Response

{
  "success": true,
  "data": "string"
}

Example

curl -X DELETE "https://poliglot.io/api/v1/iam/my-workspace/roles/<roleId>/assignees/<userId>" \
  -H "Authorization: Bearer <your-token>"

Assign role to principal

POST /api/v1/iam/{workspace}/roles/{roleId}/assignees/principals/{principalId}

Assign a role to any principal (user or agent)

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`roleId`	Yes	Role ID
`principalId`	Yes	Principal ID

Responses

Status	Description
`200`	Role assigned successfully
`404`	Role or principal not found
`409`	Principal already has this role

Example Response

{
  "success": true,
  "data": "string"
}

Example

curl -X POST "https://poliglot.io/api/v1/iam/my-workspace/roles/<roleId>/assignees/principals/<principalId>" \
  -H "Authorization: Bearer <your-token>"

Remove role from principal

DELETE /api/v1/iam/{workspace}/roles/{roleId}/assignees/principals/{principalId}

Remove a role assignment from any principal (user or agent)

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`roleId`	Yes	Role ID
`principalId`	Yes	Principal ID

Responses

Status	Description
`200`	Role assignment removed successfully
`404`	Role, principal, or assignment not found

Example Response

{
  "success": true,
  "data": "string"
}

Example

curl -X DELETE "https://poliglot.io/api/v1/iam/my-workspace/roles/<roleId>/assignees/principals/<principalId>" \
  -H "Authorization: Bearer <your-token>"

List workspace users

GET /api/v1/iam/{workspace}/users

Get all users who are members of this workspace

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug

Query Parameters

Name	Required	Type	Description
`page`	No	`integer(int32)`	Page number (1-indexed)
`pageSize`	No	`integer(int32)`	Page size

Responses

Status	Description
`200`	Users retrieved successfully
`404`	Workspace not found

Response Shape

Field	Type	Description
`id`	`string (uuid)`
`username`	`string`
`email`	`string`
`firstName`	`string`
`lastName`	`string`
`website`	`string`
`emailVerified`	`boolean`
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "string",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "website": "string",
    "emailVerified": true,
    "createdAt": "2025-03-28T14:22:03Z",
    "updatedAt": "2025-03-28T14:22:03Z"
  }
}

Example

curl -X GET "https://poliglot.io/api/v1/iam/my-workspace/users" \
  -H "Authorization: Bearer <your-token>"

Get workspace user

GET /api/v1/iam/{workspace}/users/{userId}

Get a specific user in this workspace

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`userId`	Yes	User ID

Responses

Status	Description
`200`	User retrieved successfully
`404`	User not found in workspace

Response Shape

Field	Type	Description
`id`	`string (uuid)`
`username`	`string`
`email`	`string`
`firstName`	`string`
`lastName`	`string`
`website`	`string`
`emailVerified`	`boolean`
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "username": "string",
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "website": "string",
    "emailVerified": true,
    "createdAt": "2025-03-28T14:22:03Z",
    "updatedAt": "2025-03-28T14:22:03Z"
  }
}

Example

curl -X GET "https://poliglot.io/api/v1/iam/my-workspace/users/<userId>" \
  -H "Authorization: Bearer <your-token>"

Get user roles in workspace

GET /api/v1/iam/{workspace}/users/{userId}/roles

Get all roles assigned to a user in this workspace

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`userId`	Yes	User ID

Responses

Status	Description
`200`	Roles retrieved successfully
`404`	User not found in workspace

Example Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "uri": "string",
      "label": "string",
      "description": "string",
      "matrixId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2025-03-28T14:22:03Z",
      "updatedAt": "2025-03-28T14:22:03Z"
    }
  ]
}

Example

curl -X GET "https://poliglot.io/api/v1/iam/my-workspace/users/<userId>/roles" \
  -H "Authorization: Bearer <your-token>"

Get current user's principal

GET /api/v1/iam/{workspace}/users/me/principal

Get the principal (workspace membership) for the currently authenticated user

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug

Responses

Status	Description
`200`	Principal retrieved successfully
`404`	User is not a member of this workspace

Response Shape

Field	Type	Description
`id`	`string (uuid)`
`workspaceId`	`string (uuid)`
`type`	`string`
`actor`	``
`createdAt`	`string (date-time)`

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "USER",
    "actor": "...",
    "createdAt": "2025-03-28T14:22:03Z"
  }
}

Example

curl -X GET "https://poliglot.io/api/v1/iam/my-workspace/users/me/principal" \
  -H "Authorization: Bearer <your-token>"

List roles in workspace

GET /api/v1/iam/{workspace}/roles

Get all roles defined in this workspace, optionally filtered by assignee

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug

Query Parameters

Name	Required	Type	Description
`assignee`	No	`string(uuid)`	Filter by user ID (returns only roles assigned to this user)
`principal`	No	`string(uuid)`	Filter by principal ID (returns only roles assigned to this principal)
`page`	No	`integer(int32)`	Page number (1-indexed)
`pageSize`	No	`integer(int32)`	Page size

Responses

Status	Description
`200`	Roles retrieved successfully
`404`	Workspace not found

Response Shape

Field	Type	Description
`id`	`string (uuid)`
`uri`	`string`
`label`	`string`
`description`	`string`
`matrixId`	`string (uuid)`
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uri": "string",
    "label": "string",
    "description": "string",
    "matrixId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2025-03-28T14:22:03Z",
    "updatedAt": "2025-03-28T14:22:03Z"
  }
}

Example

curl -X GET "https://poliglot.io/api/v1/iam/my-workspace/roles" \
  -H "Authorization: Bearer <your-token>"

Get role by ID

GET /api/v1/iam/{workspace}/roles/{roleId}

Get a specific role by its ID

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`roleId`	Yes	Role ID

Responses

Status	Description
`200`	Role retrieved successfully
`404`	Role not found

Response Shape

Field	Type	Description
`id`	`string (uuid)`
`uri`	`string`
`label`	`string`
`description`	`string`
`matrixId`	`string (uuid)`
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uri": "string",
    "label": "string",
    "description": "string",
    "matrixId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2025-03-28T14:22:03Z",
    "updatedAt": "2025-03-28T14:22:03Z"
  }
}

Example

curl -X GET "https://poliglot.io/api/v1/iam/my-workspace/roles/<roleId>" \
  -H "Authorization: Bearer <your-token>"

List role assignees

GET /api/v1/iam/{workspace}/roles/{roleId}/assignees

Get all principals (users and agents) assigned to a specific role

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`roleId`	Yes	Role ID

Responses

Status	Description
`200`	Assignees retrieved successfully
`404`	Role not found

Example Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
      "type": "USER",
      "actor": "...",
      "createdAt": "2025-03-28T14:22:03Z"
    }
  ]
}

Example

curl -X GET "https://poliglot.io/api/v1/iam/my-workspace/roles/<roleId>/assignees" \
  -H "Authorization: Bearer <your-token>"

List agents in workspace

GET /api/v1/iam/{workspace}/agents

Get all agents defined in matrix specs for this workspace

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug

Query Parameters

Name	Required	Type	Description
`page`	No	`integer(int32)`	Page number (1-indexed)
`pageSize`	No	`integer(int32)`	Page size

Responses

Status	Description
`200`	Agents retrieved successfully
`404`	Workspace not found

Response Shape

Field	Type	Description
`id`	`string (uuid)`
`uri`	`string`
`label`	`string`
`description`	`string`
`matrixId`	`string (uuid)`
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uri": "string",
    "label": "string",
    "description": "string",
    "matrixId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2025-03-28T14:22:03Z",
    "updatedAt": "2025-03-28T14:22:03Z"
  }
}

Example

curl -X GET "https://poliglot.io/api/v1/iam/my-workspace/agents" \
  -H "Authorization: Bearer <your-token>"

Get agent by ID

GET /api/v1/iam/{workspace}/agents/{agentId}

Get a specific agent by its ID

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`agentId`	Yes	Agent ID

Responses

Status	Description
`200`	Agent retrieved successfully
`404`	Agent not found

Response Shape

Field	Type	Description
`id`	`string (uuid)`
`uri`	`string`
`label`	`string`
`description`	`string`
`matrixId`	`string (uuid)`
`createdAt`	`string (date-time)`
`updatedAt`	`string (date-time)`

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "uri": "string",
    "label": "string",
    "description": "string",
    "matrixId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2025-03-28T14:22:03Z",
    "updatedAt": "2025-03-28T14:22:03Z"
  }
}

Example

curl -X GET "https://poliglot.io/api/v1/iam/my-workspace/agents/<agentId>" \
  -H "Authorization: Bearer <your-token>"

List agent roles

GET /api/v1/iam/{workspace}/agents/{agentId}/roles

Get all roles assigned to an agent. Agent roles are spec-driven (defined via iam:hasRole in matrix spec)

Path Parameters

Name	Required	Description
`workspace`	Yes	Workspace slug
`agentId`	Yes	Agent ID

Responses

Status	Description
`200`	Roles retrieved successfully
`404`	Agent not found

Example Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "uri": "string",
      "label": "string",
      "description": "string",
      "matrixId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2025-03-28T14:22:03Z",
      "updatedAt": "2025-03-28T14:22:03Z"
    }
  ]
}

Example

curl -X GET "https://poliglot.io/api/v1/iam/my-workspace/agents/<agentId>/roles" \
  -H "Authorization: Bearer <your-token>"

On this page