Groups API

Groups, and who is on each domain’s access list. Service account tokens only. Every request sends a token in the Authorization: Bearer header; see Get started with the API.

Give a user access to a domain

PUT /api/admin/domains/{id}/access/users/{userID}

Puts the user on the domain’s access list. Does nothing if they are already on it. Under an API token, the domain must be one of the service account’s domains (403 otherwise), and the user must have one of them too (404 otherwise). Service accounts are not users here and answer 404. Admins can’t be managed under an API token: the request is refused with 403.

Permission: Users: Manage (users:write)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The domain’s ID, from `GET /api/admin/domains`.
`userID` (required)	path	string	The user’s ID.

Response 200

The user is on the access list.

data is Success.

{
  "success": true,
  "message": "Access updated"
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, the domain isn’t one of the service account’s, the user is an admin, or the admin network allowlist refuses the caller.	“This API token doesn’t have permission for this action.” “This service account can only change access to its own domains.” “API tokens can’t create or manage admins.” “Admin access is not allowed from this network.”
404	No such domain or user, or for a removal, the user isn’t on the access list themselves. Service accounts are not users here and also answer 404.	“User not found” “Not found”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Remove a user from a domain’s access list

DELETE /api/admin/domains/{id}/access/users/{userID}

Takes the user’s own place off the domain’s access list. Access they have through a group stays. Under an API token, the domain must be one of the service account’s domains (403 otherwise), and the user must have one of them too (404 otherwise). Service accounts are not users here and answer 404. Admins can’t be managed under an API token: the request is refused with 403.

Permission: Users: Manage (users:write)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The domain’s ID, from `GET /api/admin/domains`.
`userID` (required)	path	string	The user’s ID.

Response 200

The user is off the access list.

data is Success.

{
  "success": true,
  "message": "Access updated"
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, the domain isn’t one of the service account’s, the user is an admin, or the admin network allowlist refuses the caller.	“This API token doesn’t have permission for this action.” “This service account can only change access to its own domains.” “API tokens can’t create or manage admins.” “Admin access is not allowed from this network.”
404	No such domain or user, or for a removal, the user isn’t on the access list themselves. Service accounts are not users here and also answer 404.	“User not found” “Not found”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

List groups

GET /api/admin/groups

Lists every group: Everyone first, then Local and SCIM groups by name.

Permission: groups:read (groups:read)
Service account tokens only, without Dew-Act-As.

Response 200

The groups.

data is array of Group.

{
  "success": true,
  "data": [
    {
      "id": "everyone",
      "kind": "everyone",
      "name": "Everyone",
      "email_domains": [],
      "member_count": 24,
      "created_at": "2026-09-01T10:00:00Z",
      "updated_at": "2026-09-01T10:00:00Z"
    },
    {
      "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "kind": "local",
      "name": "Legal",
      "email_domains": [],
      "member_count": 2,
      "created_at": "2026-09-14T08:32:11.402Z",
      "updated_at": "2026-09-14T08:32:11.402Z"
    },
    {
      "id": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
      "kind": "scim",
      "name": "Sales",
      "email_domains": [],
      "member_count": 9,
      "created_at": "2026-09-14T08:32:11.402Z",
      "updated_at": "2026-10-02T12:04:51Z"
    }
  ]
}

Errors

Status	When	Example message
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the admin network allowlist refuses the caller.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Create a group

POST /api/admin/groups

Creates a Local group. With email_domains, users with an email at those domains are members without being added, now and when they join later.

Permission: groups:write (groups:write)
Service account tokens only, without Dew-Act-As.

Request body

Content type application/json.

Field	Type	Description
`name` (required)	string	Must not be the name of another Local group or Everyone, ignoring case. At most 100 characters.
`email_domains`	array of string	The email rule, such as `example.com`: users with an email at these domains become members. Leave out or empty for no rule. API tokens can’t set or change it: a request that would is refused with 403.

{
  "name": "Legal",
  "email_domains": [
    "legal.example.com"
  ]
}

Response 201

The group was created.

data is Group.

{
  "success": true,
  "data": {
    "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "kind": "local",
    "name": "Legal",
    "email_domains": [
      "legal.example.com"
    ],
    "member_count": 0,
    "created_at": "2026-09-14T08:32:11.402Z",
    "updated_at": "2026-09-14T08:32:11.402Z"
  },
  "message": "Group created"
}

Errors

Status	When	Example message
400	The request is invalid.	“Invalid JSON” “Enter a group name of up to 100 characters.” “Enter email domains like example.com.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the admin network allowlist refuses the caller.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
409	Another Local group or Everyone has this name, ignoring case.	“A group with this name already exists.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Get a group

GET /api/admin/groups/{id}

Returns the group with its members, the people its email rule matches who are excluded, and the domains it gives access to. Members are left out for Everyone, which is every user except service accounts. Under an API token, only members on the service account’s domains are listed.

Permission: groups:read (groups:read)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The group’s ID.

Response 200

The group.

data is GroupDetail.

{
  "success": true,
  "data": {
    "id": "7a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "kind": "local",
    "name": "Legal",
    "email_domains": [],
    "member_count": 2,
    "created_at": "2026-09-14T08:32:11.402Z",
    "updated_at": "2026-09-14T08:32:11.402Z",
    "members": [
      {
        "user_id": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
        "email": "anna@example.com",
        "displayname": "Anna Berg",
        "source": "added",
        "avatar_url": ""
      },
      {
        "user_id": "8d4e2a7b-1f3c-4b9d-a6e5-2c7f9b0d3e45",
        "email": "bob@example.com",
        "displayname": "Bob Lund",
        "source": "added",
        "avatar_url": ""
      }
    ],
    "access": [
      {
        "domain_id": "b1c2d3e4-5f60-4a7b-8c9d-0e1f2a3b4c5d",
        "hostname": "files.example.com",
        "sole_access_count": 1
      }
    ]
  }
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the admin network allowlist refuses the caller.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such group.	“Group not found”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Update a group

PUT /api/admin/groups/{id}

Renames a Local group and sets its email rule. Leaving out email_domains removes the rule. Exclusions stay when the rule changes. SCIM groups and Everyone can’t be changed: they answer 409.

Permission: groups:write (groups:write)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The group’s ID.

Request body

Content type application/json.

Field	Type	Description
`name` (required)	string	Must not be the name of another Local group or Everyone, ignoring case. At most 100 characters.
`email_domains`	array of string	The email rule, such as `example.com`: users with an email at these domains become members. Leave out or empty for no rule. API tokens can’t set or change it: a request that would is refused with 403.

{
  "name": "Legal",
  "email_domains": [
    "legal.example.com"
  ]
}

Response 200

The group was updated.

data is Success.

{
  "success": true,
  "message": "Group updated"
}

Errors

Status	When	Example message
400	The request is invalid.	“Invalid JSON” “Enter a group name of up to 100 characters.” “Enter email domains like example.com.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the admin network allowlist refuses the caller.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such group.	“Group not found”
409	The group is a SCIM group or Everyone, or another Local group or Everyone has this name, ignoring case.	“A group with this name already exists.” “This group is managed in your identity provider.” “Everyone always includes every user.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Delete a group

DELETE /api/admin/groups/{id}

Deletes a Local group and takes it off every domain’s access list. Its members lose access they have only through this group. SCIM groups and Everyone can’t be deleted: they answer 409. API tokens can’t delete a group that gives access to domains: the request is refused with 403.

Permission: groups:write (groups:write)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The group’s ID.

Response 200

The group was deleted.

data is Success.

{
  "success": true,
  "message": "Group deleted"
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the admin network allowlist refuses the caller.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such group.	“Group not found”
409	The group is a SCIM group or Everyone, which can’t be changed here.	“This group is managed in your identity provider.” “Everyone always includes every user.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Add members to a group

POST /api/admin/groups/{id}/members

Adds users to a Local group. Adding someone who was excluded includes them again. Users already in the group and service accounts are skipped. Under an API token, only users with one of the service account’s domains who aren’t admins can be changed; anyone else is skipped. SCIM groups and Everyone answer 409.

Permission: groups:write (groups:write)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The group’s ID.

Request body

Content type application/json.

Field	Type	Description
`user_ids` (required)	array of string	The users to add, by ID.

{
  "user_ids": [
    "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e9f0a12",
    "8d4e2a7b-1f3c-4b9d-a6e5-2c7f9b0d3e45"
  ]
}

Response 200

The members were added.

data is Success.

{
  "success": true,
  "message": "Group members updated"
}

Errors

Status	When	Example message
400	The request is invalid.	“Invalid JSON” “Choose at least one user.”
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the admin network allowlist refuses the caller.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such group.	“Group not found”
409	The group is a SCIM group or Everyone, which can’t be changed here.	“This group is managed in your identity provider.” “Everyone always includes every user.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Remove a member from a group

DELETE /api/admin/groups/{id}/members/{userID}

Removes a user who was added to a Local group. If the group’s email rule matches them, they stay in through the rule; to take them out, exclude them. Under an API token, only users with one of the service account’s domains who aren’t admins can be changed; anyone else answers 404. SCIM groups and Everyone answer 409.

Permission: groups:write (groups:write)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The group’s ID.
`userID` (required)	path	string	The user’s ID.

Response 200

The member was removed.

data is Success.

{
  "success": true,
  "message": "Group members updated"
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the admin network allowlist refuses the caller.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such group, or the user isn’t in it this way.	“Group not found” “User not found in this group”
409	The group is a SCIM group or Everyone, which can’t be changed here.	“This group is managed in your identity provider.” “Everyone always includes every user.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Exclude a user from a group

PUT /api/admin/groups/{id}/exclusions/{userID}

Keeps a user the Local group’s email rule matches out of the group. Only users the rule matches can be excluded. Under an API token, only users with one of the service account’s domains who aren’t admins can be changed; anyone else answers 404. SCIM groups and Everyone answer 409.

Permission: groups:write (groups:write)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The group’s ID.
`userID` (required)	path	string	The user’s ID.

Response 200

The user was excluded.

data is Success.

{
  "success": true,
  "message": "Group members updated"
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the admin network allowlist refuses the caller.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such group, or the user isn’t in it this way.	“Group not found” “User not found in this group”
409	The group is a SCIM group or Everyone, which can’t be changed here.	“This group is managed in your identity provider.” “Everyone always includes every user.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.

Include an excluded user again

DELETE /api/admin/groups/{id}/exclusions/{userID}

Removes the exclusion, so the Local group’s email rule makes the user a member again. Under an API token, only users with one of the service account’s domains who aren’t admins can be changed; anyone else answers 404. SCIM groups and Everyone answer 409.

Permission: groups:write (groups:write)
Service account tokens only, without Dew-Act-As.

Parameters

Name	In	Type	Description
`id` (required)	path	string	The group’s ID.
`userID` (required)	path	string	The user’s ID.

Response 200

The user was included again.

data is Success.

{
  "success": true,
  "message": "Group members updated"
}

Errors

Status	When	Example message
400	The request is invalid; `message` says what to change.
401	The token is missing, wrong, revoked or expired.
403	The token lacks the permission, or the admin network allowlist refuses the caller.	“This API token doesn’t have permission for this action.” “Admin access is not allowed from this network.”
404	No such group, or the user isn’t in it this way.	“Group not found” “User not found in this group”
409	The group is a SCIM group or Everyone, which can’t be changed here.	“This group is managed in your identity provider.” “Everyone always includes every user.”
500	Something failed on the server. `error` is an error code and `ref` a reference to quote to your admin, who can find it in the system logs.