Manage users from another system

Your HR or identity system can invite new people to Dew, give them domains and deactivate leavers. If your identity provider supports SCIM, use single sign-on with SCIM provisioning instead (Enterprise): it keeps users in step without a script.

Before you start, create a service account and token with Users: View and Users: Manage, plus Settings: View to look up domain IDs. Add Users: Delete only if the system deletes accounts.

The service account manages only users who have one of its Domains, and gives users only those domains. Give each system the domains whose users it looks after. API tokens never create, invite or manage admins: those stay with people in the web app.

Find domain IDs

Users get access per domain, by ID. The service account can give its own domains only:

curl -H "Authorization: Bearer dewsa_<token>" https://files.example.com/api/admin/domains

Each domain has an id and its hostname.

Invite someone

curl -X POST -H "Authorization: Bearer dewsa_<token>" -H "Content-Type: application/json" -d '{"email":"bob@example.com","domain_ids":["<domain_id>"]}' https://files.example.com/api/admin/invites

domain_ids is required and lists the domains Bob gets, from the service account’s own. Bob gets an email to create his account; the link expires after 3 days. A pending invitation counts as a user on the license. GET /api/admin/invites lists invitations with their IDs, and POST /api/admin/invites/<id>/resend sends a new link.

To create an account with a password you set instead, use POST /api/admin/users with displayname, email, password and domain_ids.

Find a user

curl -H "Authorization: Bearer dewsa_<token>" "https://files.example.com/api/admin/users?limit=200"

Only users with one of the service account’s domains are listed. Each user has an id, email, user_status and domain_ids. Up to 200 come back per call; pass the last user’s created_at and id as cursor_ts and cursor_id for the next page.

Change someone’s domains

Give a user one of the service account’s domains, one domain per call, with no request body:

curl -X PUT -H "Authorization: Bearer dewsa_<token>" "https://files.example.com/api/admin/domains/<domain_id>/access/users/<user_id>"

Send DELETE to the same address to take the domain away again. The user must already have one of the service account’s domains, and the domain in the address must be one of them.

A removal takes away only access given to the user directly. Access through a group stays. With Groups: Manage, a token can remove a user who was added to a Local group by hand, or exclude them from it. Email rules, Everyone, SCIM groups and which domains a group is on change only in People → Groups. To see every domain a user has and how, call GET /api/admin/users/<user_id>/access: each domain in data.domains lists its routes, with a group_name for access through a group.

Deactivate someone

curl -X PUT -H "Authorization: Bearer dewsa_<token>" -H "Content-Type: application/json" -d '{"user_status":"inactive"}' "https://files.example.com/api/admin/users/<user_id>/status"

Deactivating signs them out everywhere, the desktop app included, and ends their personal tokens. Their files and requests stay. Send "active" to activate them again.

For a leaver, first give their files to a colleague who also has one of the service account’s domains:

curl -X POST -H "Authorization: Bearer dewsa_<token>" -H "Content-Type: application/json" -d '{"to_user_id":"<colleague_user_id>"}' "https://files.example.com/api/admin/users/<user_id>/transfer"

Their files and file requests, with the files received through them, move to the colleague, and their shared links keep working.

Check it worked

Each change shows up in the API straight away:

An invitation is listed by GET /api/admin/invites until Bob creates his account.
A domain you gave is in data.domains of GET /api/admin/users/<user_id>/access, with a route that has no group_name.
A deactivated user has user_status inactive in GET /api/admin/users.

If something doesn’t work

What you see	What to do
`403` with “API tokens can’t create or manage admins.”	The user or invitation is an admin’s. Manage admins in the web app.
`403` with error `License Limit Reached`	The license has no room for another user. Revoke unused invitations, deactivate users who left, or add users to your plan.
`409` when activating a user	The user is managed by SCIM, or their email domain is no longer on the single sign-on connection. Activate them in your identity provider, or use Convert to local in People → Users.
`404` for a user ID you know exists	The user has none of the service account’s domains, or it’s a service account. Manage those in People → Users or System → Integrations.
`403` with “This service account can only give users its own domains.”	Use only domain IDs from the service account’s Domains, or add the domain there.
`400` with “Choose at least one of the service account’s domains in domain_ids.”	Add `domain_ids` with at least one of the service account’s domains.
`403` with “This service account can only change access to its own domains.”	Use a domain ID from the service account’s Domains, or add the domain there.
`404` with “Not found” when removing a domain	The user has the domain only through a group, or not at all. Check `GET /api/admin/users/<user_id>/access`.

Every endpoint used here is in the Users API reference.