Skip to main content
Version: 3.6.0

Manage platform user accounts

As a platform administrator you can create a user account and give the person their first password yourself. The platform sends no email, so this also works when your installation has no mail server.

A new account created with the API belongs to no tenant. Adding it to a tenant is a separate step, described in Manage an account's tenants in the portal. In the portal, you can add tenant memberships while you create the account.

Who can use it​

Every operation needs permission to manage tenants on the platform. It is the same permission that opens the platform Tenants and Users pages. An API caller without it gets permission_denied. These are platform operations, so make API calls without selecting a tenant; a call made inside a tenant also gets permission_denied.

Find an account in the portal​

Click Manage platform in the sidebar, then Users.

The page shows the accounts 15 at a time, in username order. The selector beside the search box shows 25, 50 or 100 accounts a page instead.

To find one account, type part of its username or email address in the search box. The portal searches every account on the platform, not only the accounts on the page. Upper and lower case do not matter, and the text may be anywhere in the name or the address.

To read the other accounts, click Previous page or Next page below the table.

The table has a Username column, an Email column and a Tenants column. If a user is in more than three tenants, the column shows the first three and how many more there are. Users who are in no tenant show a dash.

Click a username to open that user's page. The settings button at the end of the row opens the same page.

Create an account in the portal​

  1. Click Manage platform in the sidebar, then Users.
  2. Click Create user.
  3. Fill in Username. You can leave Email (optional) empty.
  4. Fill in Temporary password. No email is sent, so give the password to the person yourself, over a safe channel.
  5. Under Tenant memberships (optional), click Add tenant to add a membership row. Choose the Tenant and the Role the person gets there: Member, Editor or Owner. Add one row per tenant, with its own role. You can also leave memberships empty and add tenants later.
  6. Click Create user.

The new account's page opens and the portal says User created. The person must choose a new password the first time they sign in.

If the account is created but a tenant membership cannot be added, the portal opens the account's Tenants tab and shows a message. Check the current memberships and add the missing ones there.

Change an account in the portal​

Click Manage platform in the sidebar, then Users, then the person's username. Their page has a General tab and a Tenants tab.

On General:

  • Account shows the username and email address. Click Edit to change the email address, then Save. Leave the field empty to remove the address.
  • Account Status shows Enabled or Disabled. Click Disable to turn the account off, or Enable to turn it on again. Disabling blocks new sign-ins and keeps the account and its tenant memberships. You cannot disable your own account, so that button is unavailable on your own page. See how disabling affects sessions and API keys.
  • Password: Click Set temporary password, type the new password and click Save. No email is sent, so give the password to the person yourself, over a safe channel. They must choose their own password when they next sign in. People who still know their password can change it themselves on their own account page, so use this when someone has forgotten theirs. See Manage your account. An account that signs in through your organization's sign-in service has no Set temporary password button; see Accounts you cannot change.

Use the Tenants tab to manage tenant memberships and roles.

Manage an account's tenants in the portal​

Add a user to tenants:

  1. Find the user in the list and click their username
  2. Open the Tenants tab
  3. Click Add to tenant
  4. Choose the Tenant and the Role the user gets there: Member, Editor or Owner. Owner makes the user an administrator of the tenant
  5. To add more tenants, click Add tenant and fill in another row. Each tenant has its own role
  6. Click Add

The user becomes a member at once. There is no invitation and the user does not have to accept anything. Tenants the user is already in are not offered.

Remove a user from a tenant:

  1. Find the user in the list and click their username
  2. Open the Tenants tab
  3. Under Current memberships, click the remove button next to the tenant
  4. Confirm with Remove

The user is taken out of that tenant completely, including its groups, and loses access to the tenant's services. You do not have to be an administrator of the tenant to do this.

Change a user's role in a tenant:

  1. Find the user in the list and click their username
  2. Open the Tenants tab
  3. Under Current memberships, click the edit button next to the role
  4. Choose the new role and click Save

The new role applies at once.

Delete an account in the portal​

  1. Click Manage platform in the sidebar, then Users, then the person's username.
  2. Click Delete.
  3. Type the username exactly as shown, then click Delete.

The account is removed from the platform and from every tenant it is in. This cannot be undone. You cannot delete your own account, so the Delete button is unavailable on your own page.

Add instructions to the invitation email​

Someone invited to a tenant who has no account yet gets an email to set their password. If people must do something before they can reach the portal, such as connecting to your organization's VPN, add instructions to that email. They apply to every invitation, whichever tenant sends it. Someone who already has an account gets no email, so they don't see the instructions.

  1. Click Manage platform in the sidebar, then Users.
  2. Click Invitation email.
  3. Type the instructions under Additional instructions, then click Save.

The instructions appear at the top of the email, under Before you start. They are plain text of up to 4000 characters: line breaks are kept, and most mail programs make a web address clickable. Emails sent from then on use them, including resent invitations. To remove them, clear the field and click Save.

Operations​

All operations are POST requests with a JSON body.

OperationWhat it does
ListPlatformUsersList the accounts on the platform
GetPlatformUserRead one account
CreatePlatformUserCreate an account with a temporary password
UpdatePlatformUserChange the email address, or turn the account off or on
SetPlatformUserPasswordGive the account a new temporary password
DeletePlatformUserDelete the account

List and find accounts​

POST /cmind.users.v1.UserManagementService/ListPlatformUsers

Request Fields:

  • search (optional): Returns only accounts whose username or email address contains this text. Upper and lower case do not matter.
  • page (optional): pageSize is the largest number of accounts to return. The default is 50 and the largest allowed is 200. To read the next page, send the endCursor of the previous response back as cursor.

Response Fields:

  • users: One entry per account, sorted by username, with userId, username, email, enabled, systemAccount and tenants. Each entry in tenants has tenantId, tenantName and role.
  • page: endCursor and hasNextPage tell you whether more accounts follow.

If the tenant list of one account cannot be read, that account comes back with an empty tenants list. The rest of the page is still returned.

To read a single account, use POST /cmind.users.v1.UserManagementService/GetPlatformUser with userId. It returns the same fields, under user, and externalLogin next to it: true when the account signs in through a user directory or an external identity provider. An unknown ID fails with not_found.

Listing users used to be an operation of cmind.tenants.v1.TenantService. That address no longer works; use this one.

Create an account​

POST /cmind.users.v1.UserManagementService/CreatePlatformUser

Creates a new account and sets its first password. The account is turned on at once.

Request Fields:

  • username (required): The name the person signs in with.
  • password (required): The first password, between 1 and 1024 characters. It must meet the password rules of your identity provider.
  • email (optional): The person's email address. Leave it out if you do not have one. Spaces around the address are removed and the address is stored in lower case.

Response Fields:

  • userId: The ID of the new account. Every other operation on this page uses it.

The password is always temporary. The person must choose a new one the first time they sign in. The platform tells them nothing, so pass the username and the password on yourself, over a safe channel.

The call never changes an account that already exists. If the username or the email address is already in use, it fails with already_exists. If the password or the account details do not meet the rules of your identity provider, it fails with invalid_argument.

Change an email address, or turn an account off​

POST /cmind.users.v1.UserManagementService/UpdatePlatformUser

Request Fields:

  • userId (required): The ID of the account.
  • email (optional): The new email address. Leave the field out to keep the current address. Send an empty string to remove the address.
  • enabled (optional): false turns the account off, true turns it on again. Leave the field out to keep the account as it is.

Send at least one of email and enabled. A request with neither fails with invalid_argument.

A new email address counts as unverified until the person confirms it.

Turning an account off stops the person's next sign-in, and stops their open sessions from being renewed. An access token issued before the change keeps working until it expires, which is about an hour with the default settings. API keys the person owns are not affected: the platform checks the key, not the account behind it. Disable or revoke those keys separately if the person must lose access at once.

You cannot turn your own account off. That call fails with failed_precondition.

Give a user a new password​

POST /cmind.users.v1.UserManagementService/SetPlatformUserPassword

Replaces the account's password. Use this when someone forgets their password.

A person who still knows their password does not need you for this. They can change it themselves; see Manage your account.

Request Fields:

  • userId (required): The ID of the account.
  • password (required): The new password, between 1 and 1024 characters.

The new password is temporary as well: the person must choose their own password the next time they sign in. Nothing is emailed, so hand the password over yourself, over a safe channel.

If the password does not meet the rules of your identity provider, the call fails with invalid_argument. An unknown ID fails with not_found.

Delete an account​

POST /cmind.users.v1.UserManagementService/DeletePlatformUser

Request Fields:

  • userId (required): The ID of the account.

Deleting an account removes it from the platform and from every tenant it is in. This cannot be undone. An unknown ID fails with not_found.

Accounts you cannot change​

Some accounts are protected. A call that tries to change one fails with failed_precondition:

  • Your own account. You cannot delete it and you cannot turn it off.
  • The platform's own service accounts. You cannot change them, delete them, or set a password for them. ListPlatformUsers and GetPlatformUser mark them with systemAccount: true, so you can leave them out of your own tools.
  • Accounts that sign in elsewhere. When an account signs in through a user directory or an external identity provider, you cannot set a password for it. A password set in the platform would become a second way to sign in that skips the provider, including its multi-factor checks and its account disable. GetPlatformUser marks these accounts with externalLogin: true. An account that has no password yet, such as an invited person who has not finished setup, is not one of them: you can set its first password.

In the portal, the Password section of an account that signs in elsewhere says This user signs in through your organization's sign-in service, which manages their password. and has no Set temporary password button.

A platform service account's page says This account is managed by the system. It has no controls to change the account, set a password, delete it, or change its tenant memberships.