Entity Users
Entity Users
Manage user access to entities with role-based permissions (viewer, editor, admin, staff; the accountant role cannot be assigned here).
The Entity User object
Attributes
Add user to entity
/entities/usersAdd an existing white-label user for this account to the entity or send an invitation. The accountant role cannot be assigned this way (422). Existing account users must accept the invitation so they receive separate entity-user access. With silent: true no email is sent (send_invite is ignored): a missing white-label user is created immediately (no password, optional metadata) and linked to the entity, and an existing white-label user is linked. Silent provisioning requires an account API key or an account owner/admin signed in directly (an interactive session); delegated (SSO) tokens are rejected. The new user's email counts as verified when the credential is an account API key or a user token whose email is verified; otherwise the user must verify their email before sending documents by email. Silent provisioning can be followed by POST /entities/users/{user_id}/token with ttl to embed the user.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Body parameters
Email address of the user to add or invite
Custom string key-value data stored on the white-label user, for your own use (for example an external user ID). Only accepted when silent is true; when the user already exists it replaces their metadata. Update it later with PATCH /entities/users/{user_id} and search it with the query parameter of GET /entities/users.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.entityUsers.addEntityUser({
email: "newuser@example.com",
role: "editor",
send_invite: true
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
User name
User email
Custom key-value data stored on the user. Only populated for the account's own white-label users; always {} for other users, whose metadata belongs to them.
{
"user_id": "user_new123",
"entity_id": "ent_xyz789",
"role": "editor",
"email": "newuser@example.com",
"name": "Alex Carter",
"invited_by_user_id": "user_abc123",
"created_at": "2024-01-20T00:00:00.000Z",
"metadata": {}
}List entity users
/entities/usersRetrieve all users who have access to the current entity, including their roles. Use query to find a user by email or by the metadata stored on the account's white-label users, for example ?query={"metadata":{"external_id":"u_123"}}. Metadata conditions only match the account's own white-label users; set metadata with PATCH /entities/users/{user_id}.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Query parameters
JSON query object for filtering results. Supports MongoDB-style operators.
Array columns (such as an item's categories) compare as sets: a direct value asks whether the list contains it, contains takes an array and requires all of them, in matches any of them, and notIn matches none. Scalar operators such as gt do not apply and are ignored.
Supported operators:
- equals or direct value - Exact match (default)
- gte - Greater than or equal
- lte - Less than or equal
- gt - Greater than
- lt - Less than
- in - Value in array
- notIn - Value not in array
- contains - String contains (case-insensitive)
- startsWith - String starts with
- endsWith - String ends with
- between - Value between two numbers/dates [min, max]
Allowed fields: metadata, email
Examples:
- {"total": {"gte": 1000}} - Invoices over 1000
- {"customer.name": {"contains": "Acme"}} - Customer name contains "Acme"
- {"date": {"between": ["2025-01-01", "2025-12-31"]}} - Date range
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.entityUsers.list({
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"data": [
{
"user_id": "user_abc123",
"entity_id": "ent_xyz789",
"role": "admin",
"email": "admin@example.com",
"name": "Morgan Vega",
"invited_by_user_id": null,
"created_at": "2024-01-01T00:00:00.000Z",
"metadata": {}
},
{
"user_id": "user_def456",
"entity_id": "ent_xyz789",
"role": "editor",
"email": "editor@example.com",
"name": "Riley Nova",
"invited_by_user_id": "user_abc123",
"created_at": "2024-01-15T00:00:00.000Z",
"metadata": {
"external_id": "u_123"
}
}
]
}Get entity user access state
/entities/users/accessReturn the current user's account/entity access state for entity-user management. This is separate from country or compliance feature availability.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.entityUsers.getAccess({
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"account_id": "acc_507f1f77bcf86cd799439011",
"account_role": "admin",
"entity_id": "ent_507f1f77bcf86cd799439011",
"entity_role": null,
"is_account_admin": true,
"is_entity_admin": false,
"account_admin_override": true,
"can_manage_entity_users": true,
"can_operational_write": true,
"can_read_entity": true,
"can_manage_entity_settings": true,
"can_use_own_documents": true,
"enforce_entity_admin_preservation": false
}Update user role or metadata
/entities/users/{user_id}Update a user's role, metadata, or both. Send at least one of role and metadata. Roles you can assign: viewer (read-only), editor (read+write), admin (full access), staff (issues invoices and sees only their own). The accountant role (works like editor and also uses the accounting module) cannot be assigned here: a request naming it is refused with 422, and so is changing the role of a user who already is an accountant (remove them with DELETE /entities/users/{user_id} instead). metadata replaces the stored object as a whole (string key-value data, up to 50 keys; null clears it) and is only available for the entity account's own white-label users (400 otherwise). Omitted fields are left unchanged.
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Space Invoices resource identifier (format: {prefix}_{hex24})
Body parameters
Replaces the white-label user's metadata. Send null to clear it. Omit to leave it unchanged. Only available for white-label users of the entity's account.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.entityUsers.update("inv_6595a27b5d35015c3ef0c3fd", {
role: "admin"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
User name
User email
Custom key-value data stored on the user. Only populated for the account's own white-label users; always {} for other users, whose metadata belongs to them.
{
"user_id": "user_def456",
"entity_id": "ent_xyz789",
"role": "admin",
"email": "editor@example.com",
"name": "Riley Nova",
"invited_by_user_id": "user_abc123",
"created_at": "2024-01-15T00:00:00.000Z"
}Remove user from entity
/entities/users/{user_id}Remove a user's access to the entity. This does not delete the user account.
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Space Invoices resource identifier (format: {prefix}_{hex24})
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
await sdk.entityUsers.removeEntityUser("inv_6595a27b5d35015c3ef0c3fd", {
entity_id: "YOUR_ENTITY_ID"
});
console.log('Deleted successfully');Returns
{
"message": "User removed from entity"
}Generate user access token
/entities/users/{user_id}/tokenGenerate a delegated SSO access token for a WL user to enable SSO-like redirect. Requires an account API key or a non-impersonated account owner/admin signed in directly (an interactive session); entity API keys, entity-only roles, account members, and delegated (SSO) tokens are rejected. The token has the standard one-year session TTL but cannot authorize user-presence-sensitive operations such as account deletion, so callers must treat issuance as a privileged account-level operation. Pass ttl (300 to 86400 seconds) to receive a short-lived delegated_embed token for embedding the user's app instead; it cannot be extended. An embed session can call only the routes the embedded UI needs, and can never manage users, invitations, memberships or account settings, mint other credentials (tokens, API keys, impersonation), manage passkeys, two-factor or till operator PINs, or delete the account; a request to any other route is refused with 403.
Header parameters
Optional entity ID specifying which entity context to use for this operation.
Path parameters
Space Invoices resource identifier (format: {prefix}_{hex24})
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.entityUsers.generateEntityUserToken("inv_6595a27b5d35015c3ef0c3fd", {
ttl: 900
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "session_e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"user_id": "user_def456",
"ttl": 31536000,
"scope": "delegated_sso",
"created_at": "2024-01-20T10:00:00.000Z",
"updated_at": "2024-01-20T10:00:00.000Z",
"entity_id": "ent_xyz789"
}