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 Managing Users Across Tenants. 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.

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.

Use the Tenants tab to manage tenant memberships and roles.

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.

Operations

All operations are POST requests with a JSON body.

Operation	What it does
ListPlatformUsers	List the accounts on the platform
GetPlatformUser	Read one account
CreatePlatformUser	Create an account with a temporary password
UpdatePlatformUser	Change the email address, or turn the account off or on
SetPlatformUserPassword	Give the account a new temporary password
DeletePlatformUser	Delete 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. 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.

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

Two kinds of account 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.

In the portal, 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.