Create Organization Role

(v2)

POST

Creates a custom organization role from a set of organization policies and returns the role. Its permissions are the union of what those policies grant, so a role created with an empty policyIds can do nothing until you attach one, and it grants nobody anything until a member is assigned to it.

POST/v2/organization/roles

curl -X POST "https://api.confident-ai.com/v2/organization/roles" \
  -H "CONFIDENT_API_KEY: <ORGANIZATION-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Billing Auditor",
  "description": "Read-only access to invoices and model costs.",
  "policyIds": [
    "<POLICY-ID>"
  ]
}'

200

{
  "success": true,
  "data": {
    "id": "<ROLE-ID>",
    "name": "Billing Auditor",
    "description": "Read-only access to invoices and model costs.",
    "policies": [
      {
        "id": "<POLICY-ID>",
        "name": "Billing read-only"
      }
    ],
    "organizationId": "<ORGANIZATION-ID>"
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The organization API key for your Confident AI organization.

Request body

namestringRequired
The name of the role, unique among the roles the organization or project can use. It cannot match the name of a global, system-defined role, compared without regard to case.
descriptionstring | null
What the role is for. On an update, omit it to leave the stored description unchanged, or send null to clear it.
policyIdslist of stringsRequired
The ids of the policies to attach to the role, which is what gives the role its permissions. This is the role's complete policy set: on an update the list replaces what is stored rather than adding to it, and an empty array leaves the role with no permissions at all. Discover assignable policies with the policies endpoint of the same scope.

Response

Create Organization Role succeeded.

successboolean
Indicates if the request was successful.
dataobject
A named set of organization policies that a member can hold. A member holds at most one organization role, and every organization permission they have comes from the policies attached to it.
Show 5 propertiesHide 5 properties
- idstring
  The id of the role, generated by Confident AI.
- namestring
  The name of the role.
- descriptionstring | null
  What the role is for, or null when it has no description.
- policieslist of objects
  The organization policies attached to the role, whose permissions together are everything a member holding it can do. A global role's permissions are system-defined rather than drawn from policies, so its list is empty.
  Show 2 propertiesHide 2 properties
  - idstring
    The id of the policy, generated by Confident AI.
  - namestring
    The name of the policy.
- organizationIdstring | null
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI