Sotion

Access Groups

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 /access-groups

Create a custom access group

curl --request POST \
  --url 'https://api.sotion.so/api/v1/access-groups' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "key": "value"
}'
{
  "data": {
    "id": "<uuid>",
    "name": "<string>",
    "description": "<string>",
    "type": "custom",
    "memberCount": 1,
    "createdAt": "<date-time>",
    "updatedAt": "<date-time>"
  }
}

Access group created.

Authorizations

  • Authorization string required header

    Per-site API key (prefix: so_...). Each key is scoped to exactly one Sotion site — the site context is determined entirely by the key. No site ID is needed in any URL. Pass as: Authorization: Bearer so_...

Request Body

application/json
  • name string required

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

  • description string nullable

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

Response

application/json
  • Location string response header

    URL of the created access group.

  • X-RateLimit-Limit integer response header

    Maximum requests allowed in the current window.

  • X-RateLimit-Remaining integer response header

    Requests remaining in the current window.

  • X-RateLimit-Reset integer response header

    Unix timestamp (seconds) when the rate limit window resets.

  • X-Request-Id string (uuid) response header

    Unique request identifier for support and debugging.

  • data object
    + Show Child Attributes
    • id string (uuid)

      Unique identifier (UUID) for the access group.

    • name string

      Display name of the access group.

    • description string nullable

      Optional description of the group's purpose.

    • type string enum enum

      'custom' = user-created via API or dashboard, can be modified and deleted. 'scope' = automatically created from a Notion collection, read-only via API. Allowed values: custom, scope.

    • memberCount integer

      Number of members currently in this group.

    • createdAt string (date-time) nullable

      When the group was created.

    • updatedAt string (date-time) nullable

      When the group was last modified.