---
title: "Create acl"
method: POST
path: "/v1/acl"
tags: ["Acls"]
---

# Create acl

`POST /v1/acl`

Create a new acl. If there is an existing acl with the same contents as the one specified in the request, will return the existing acl unmodified

## Request body

- AclItem — An ACL grants a certain permission or role to a certain user or group on an object. ACLs are inherited across the object hierarchy. So for example, if a user has read permissions on a project, they will also have read permissions on any experiment, dataset, etc. created within that project. To restrict a grant to a particular sub-object, you may specify `restrict_object_type` in the ACL, as part of a direct permission grant or as part of a role.
  - `object_type` 'organization' | 'project' | 'experiment' | 'dataset' | 'prompt' | 'prompt_session' | 'group' | 'role' | 'org_member' | 'project_log' | 'org_project', required — The object type that the ACL applies to
  - `object_id` string, uuid, required — The id of the object the ACL applies to
  - `user_id` string, uuid, nullable — Id of the user the ACL applies to. Exactly one of `user_id` and `group_id` will be provided
  - `group_id` string, uuid, nullable — Id of the group the ACL applies to. Exactly one of `user_id` and `group_id` will be provided
  - `permission` 'create' | 'read' | 'update' | 'delete' | 'create_acls' | 'read_acls' | 'update_acls' | 'delete_acls', nullable — Permission the ACL grants. Exactly one of `permission` and `role_id` will be provided
  - `restrict_object_type` 'organization' | 'project' | 'experiment' | 'dataset' | 'prompt' | 'prompt_session' | 'group' | 'role' | 'org_member' | 'project_log' | 'org_project', nullable — When setting a permission directly, optionally restricts the permission grant to just the specified object type. Cannot be set alongside a `role_id`.
  - `role_id` string, uuid, nullable — Id of the role the ACL grants. Exactly one of `permission` and `role_id` will be provided

## Response `200`

Returns the new acl object

- Acl — An ACL grants a certain permission or role to a certain user or group on an object. ACLs are inherited across the object hierarchy. So for example, if a user has read permissions on a project, they will also have read permissions on any experiment, dataset, etc. created within that project. To restrict a grant to a particular sub-object, you may specify `restrict_object_type` in the ACL, as part of a direct permission grant or as part of a role.
  - `id` string, uuid, required — Unique identifier for the acl
  - `object_type` 'organization' | 'project' | 'experiment' | 'dataset' | 'prompt' | 'prompt_session' | 'group' | 'role' | 'org_member' | 'project_log' | 'org_project', required — The object type that the ACL applies to
  - `object_id` string, uuid, required — The id of the object the ACL applies to
  - `user_id` string, uuid, nullable — Id of the user the ACL applies to. Exactly one of `user_id` and `group_id` will be provided
  - `group_id` string, uuid, nullable — Id of the group the ACL applies to. Exactly one of `user_id` and `group_id` will be provided
  - `permission` 'create' | 'read' | 'update' | 'delete' | 'create_acls' | 'read_acls' | 'update_acls' | 'delete_acls', nullable — Permission the ACL grants. Exactly one of `permission` and `role_id` will be provided
  - `restrict_object_type` 'organization' | 'project' | 'experiment' | 'dataset' | 'prompt' | 'prompt_session' | 'group' | 'role' | 'org_member' | 'project_log' | 'org_project', nullable — When setting a permission directly, optionally restricts the permission grant to just the specified object type. Cannot be set alongside a `role_id`.
  - `role_id` string, uuid, nullable — Id of the role the ACL grants. Exactly one of `permission` and `role_id` will be provided
  - `_object_org_id` string, uuid, required — The organization the ACL's referred object belongs to
  - `created` string, date-time, nullable — Date of acl creation

## Other responses

- `400` — The request was unacceptable, often due to missing a required parameter
- `401` — No valid API key provided
- `403` — The API key doesn’t have permissions to perform the request
- `429` — Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
- `500` — Something went wrong on Braintrust's end. (These are rare.)

---

[API](https://skmtc.net/braintrustdata/apis/braintrust-api.md) · [All operations](https://skmtc.net/braintrustdata/apis/braintrust-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/braintrustdata/braintrust-api/revisions/9d216c8243fe/schema)