Skip to main content
POST
/
v1
/
role
Create role
curl --request POST \
  --url https://api.braintrust.dev/v1/role \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "description": "<string>",
  "member_permissions": [
    {
      "permission": "create",
      "restrict_object_type": "organization"
    }
  ],
  "member_roles": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "org_name": "<string>"
}'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "org_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "description": "<string>",
  "deleted_at": "2023-11-07T05:31:56Z",
  "member_permissions": [
    {
      "permission": "create",
      "restrict_object_type": "organization"
    }
  ],
  "member_roles": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

Authorizations

​
Authorization
string
header
required

Most Braintrust endpoints are authenticated by providing your API key as a header Authorization: Bearer [api_key] to your HTTP request. You can create an API key in the Braintrust organization settings page.

Body

application/json

Any desired information about the new role object

​
name
string
required

Name of the role

Minimum length: 1
​
description
string | null

Textual description of the role

​
member_permissions
object[] | null

(permission, restrict_object_type) tuples which belong to this role

​
member_roles
string<uuid>[] | null

Ids of the roles this role inherits from

An inheriting role has all the permissions contained in its member roles, as well as all of their inherited permissions

​
org_name
string | null

For nearly all users, this parameter should be unnecessary. But in the rare case that your API key belongs to multiple organizations, you may specify the name of the organization the role belongs in.

Response

Returns the new role object

A role is a collection of permissions which can be granted as part of an ACL

Roles can consist of individual permissions, as well as a set of roles they inherit from

​
id
string<uuid>
required

Unique identifier for the role

​
name
string
required

Name of the role

​
org_id
string<uuid> | null

Unique id for the organization that the role belongs under

A null org_id indicates a system role, which may be assigned to anybody and inherited by any other role, but cannot be edited.

It is forbidden to change the org after creating a role

​
user_id
string<uuid> | null

Identifies the user who created the role

​
created
string<date-time> | null

Date of role creation

​
description
string | null

Textual description of the role

​
deleted_at
string<date-time> | null

Date of role deletion, or null if the role is still active

​
member_permissions
object[] | null

(permission, restrict_object_type) tuples which belong to this role

​
member_roles
string<uuid>[] | null

Ids of the roles this role inherits from

An inheriting role has all the permissions contained in its member roles, as well as all of their inherited permissions