Web API

Press shift + S to search API reference.

Enterprises

Remove user from enterprise

posthttps://api.airtable.com/v0/meta/enterpriseAccounts/{enterpriseAccountId}/users/{userId}/remove

Unshare a user from all enterprise workspaces, bases, interfaces, and user groups. If applicable, the user will also have their admin access revoked.

Returns lists of unsharing and sharing actions performed as part of the user removal.

Requirements

AuthenticationPersonal access token, OAuth integration
Scopeenterprise.user:write
User role

Enterprise admin

Billing plansEnterprise (pre-2023.08 legacy plan), Enterprise Scale

Path parameters

enterpriseAccountId
string
userId
string

Request body

removeFromDescendants
optional<boolean>

If true, removes the user from descendant enterprise accounts as well. Only enterprise accounts with the Enterprise Hub feature enabled have descendant enterprise accounts.

replacementOwnerId
optional<string>

If the user is the sole owner of any workspaces, you must specify a replacementOwnerId to be added as the new owner of such workspaces. If the user is not the sole owner of any workspaces, replacementOwnerId is optional and will be ignored if provided.

isDryRun
optional<boolean>

Response format

wasUserRemovedAsAdmin
boolean

If removeFromDescendants is true, this field represents whether the user was removed as an admin of this enterprise account or its descendants.

shared
object

A list of JSON objects representing workspaces that replacementOwnerId was shared to.

workspaces
array of the below object
enterpriseAccountId
optional<string>

Only returned when removeFromDescendants is true

userId
optional<string>

A user ID

deletedTime
string | null
permissionLevel
"none" | "read" | "comment" | "edit" | "create" | "owner"
workspaceId
string
workspaceName
string
unshared
object

A list of JSON objects representing workspaces, bases, and interfaces the user was unshared from.

bases
array of the below object
baseId
string

Base ID, a unique identifier for a base.

userId
string

A user ID

enterpriseAccountId
optional<string>

Only returned when removeFromDescendants is true

baseName
string
deletedTime
string | null
formerPermissionLevel
"none" | "read" | "comment" | "edit" | "create" | "owner"
interfaces
array of the below object
baseId
string

Base ID, a unique identifier for a base.

userId
string

A user ID

enterpriseAccountId
optional<string>

Only returned when removeFromDescendants is true

deletedTime
string | null
formerPermissionLevel
"none" | "read" | "comment" | "edit" | "create" | "owner"
interfaceId
string
interfaceName
string
workspaces
array of the below object
userId
string

A user ID

enterpriseAccountId
optional<string>

Only returned when removeFromDescendants is true

deletedTime
string | null
formerPermissionLevel
"none" | "read" | "comment" | "edit" | "create" | "owner"
workspaceId
string
workspaceName
string

Error responses

Cannot perform action on self (403)
You are not permitted to perform this operation on yourself. If necessary, another admin should do it.
{
"error": {
"message": "You are not permitted to perform this operation on yourself",
"type": "INVALID_PERMISSIONS"
}
}
Email not verified (403)
replacementOwnerId, if required, must correspond to a verified user account.
{
"error": {
"message": "Replacement owner must have verified email",
"type": "INVALID_PERMISSIONS"
}
}
Enterprise invite restrictions (403)
replacementOwnerId, if required, must abide by the enteprise account's invite restrictions.
{
"error": {
"message": "You cannot use that replacementOwnerId because of this enterprise account's invite restrictions",
"type": "INVALID_PERMISSIONS"
}
}
Removing replacement owner (403)
TBD
{
"error": {
"message": "Replacement owner must be different from the users being removed",
"type": "INVALID_PERMISSIONS"
}
}
Removing sole owner (403)
If the user is the sole owner of a workspace, replacementOwnerId must be provided in the request body.
{
"error": {
"message": "Replacement owner is required if to-be-removed users are the sole owners on workspace(s)",
"type": "INVALID_PERMISSIONS"
}
}
Replacement owner not found (403)
TBD
{
"error": {
"message": "No user with that replacementOwnerId could be found",
"type": "INVALID_PERMISSIONS"
}
}
Request (example)
Copy
$
curl -X POST "https://api.airtable.com/v0/meta/enterpriseAccounts/{enterpriseAccountId}/users/{userId}/remove" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
--data '{
"replacementOwnerId": "usrL2PNC5o3H4lBEi"
}'
200 – Response (example)
{
"shared": {
"workspaces": [
{
"deletedTime": null,
"permissionLevel": "owner",
"userId": "usrL2PNC5o3H4lBEi",
"workspaceId": "wsp00000000000000",
"workspaceName": "Workspace name"
}
]
},
"unshared": {
"bases": [
{
"baseId": "app00000000000000",
"baseName": "Base name",
"deletedTime": null,
"formerPermissionLevel": "create",
"userId": "usr00000000000000"
}
],
"interfaces": [
{
"baseId": "app00000000000000",
"deletedTime": null,
"formerPermissionLevel": "create",
"interfaceId": "pgb00000000000000",
"interfaceName": "Interface name",
"userId": "usr00000000000000"
}
],
"workspaces": [
{
"deletedTime": null,
"formerPermissionLevel": "owner",
"userId": "usr00000000000000",
"workspaceId": "wsp00000000000000",
"workspaceName": "Workspace name"
}
]
},
"wasUserRemovedAsAdmin": true
}