curl --request POST \
  --url https://{region}.api.plerion.com/v1/organization/role-assignments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "roleId": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
  "principal": {
    "type": "group",
    "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"
  }
}
'

{
  "data": {
    "principal": {
      "type": "user",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "roleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "roleScope": "organization",
    "tenantId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "createdBy": "<string>"
  }
}

{
  "errors": [
    {
      "code": "TenantIdRequired",
      "message": "tenantId is required for this role"
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  ]
}

{
  "errors": [
    {
      "code": "RoleNotFound",
      "message": "role not found"
    }
  ]
}

{
  "errors": [
    {
      "code": "RoleHasAssignments",
      "message": "role has active assignments; revoke them first"
    }
  ]
}

Assign a role

Grants a built-in or custom role to a user or a user group. For the built-in Tenant admin and Tenant read-only roles, tenantId names the one tenant the grant applies to and is required; for every other role it is not accepted, because a custom role is already bound to its tenant. A tenant that is not in your organization answers 404 TenantNotFound, and a user that does not exist answers 404 UserNotFound. Granting the same role to the same principal for the same tenant twice answers 409 AssignmentAlreadyExists. Users your identity provider manages over SCIM can be granted roles directly, like any other user. Requires an organization API key with read and write access.

POST

organization

role-assignments

curl --request POST \
  --url https://{region}.api.plerion.com/v1/organization/role-assignments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "roleId": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
  "principal": {
    "type": "group",
    "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"
  }
}
'

{
  "data": {
    "principal": {
      "type": "user",
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    },
    "roleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "roleScope": "organization",
    "tenantId": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "createdBy": "<string>"
  }
}

{
  "errors": [
    {
      "code": "TenantIdRequired",
      "message": "tenantId is required for this role"
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  ]
}

{
  "errors": [
    {
      "code": "<string>",
      "message": "<string>",
      "field": "<string>"
    }
  ]
}

{
  "errors": [
    {
      "code": "RoleNotFound",
      "message": "role not found"
    }
  ]
}

{
  "errors": [
    {
      "code": "RoleHasAssignments",
      "message": "role has active assignments; revoke them first"
    }
  ]
}

Authorizations

Authorization

string

header

required

Plerion organization API key (plerion_oak_…), created by an organization admin in the Plerion app.

Body

application/json

roleId

string<uuid>

required

principal

object

required

Show child attributes

tenantId

string<uuid>

Required for the built-in Tenant admin and Tenant read-only roles, not accepted for any other role.

Response

The created assignment.

data

object

Show child attributes

Overview

API documentation

Organization API

SCIM API

Assign a role

Authorizations

Body

Response