Create a custom access group

Creates a new custom access group. Only name is required — description is optional.

Only custom groups can be created via the API. Scope groups are automatically managed from Notion collections.

Returns 409 Conflict if an access group with the same name already exists on this site.

POST /api/v1/access-groups

Bearer token

curl 'https://api.sotion.so/api/v1/access-groups' \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "example",
  "description": "example"
}'

{
  "data": {
    "id": "123e4567-e89b-42d3-a456-426614174000",
    "name": "example",
    "description": "example",
    "type": "custom",
    "memberCount": 1,
    "createdAt": "2026-01-01T12:00:00Z",
    "updatedAt": "2026-01-01T12:00:00Z"
  }
}

Access group created.

Body

· CreateAccessGroupRequest

required application/json

name string · min length: 1· max length: 100 required

Display name for the access group. Must be unique per site. 1-100 characters.

description string · max length: 500· nullable

Optional description of the group's purpose. Max 500 characters.

Body

Responses