Identity Access Management

This document describes how to manage access to organizations, projects, resources, roles, and user profiles in TiDB Cloud.

Before accessing TiDB Cloud, create a TiDB Cloud account. You can either sign up with email and password so that you can manage your password using TiDB Cloud, or choose your Google, GitHub, or Microsoft account for single sign-on (SSO) to TiDB Cloud.

Organizations, projects, and resources

TiDB Cloud uses a hierarchical structure based on organizations, projects, and resources to help you manage users and TiDB deployments.

An organization is a top-level entity (such as a company or a customer) that you use to manage your TiDB Cloud accounts (including a management account with any number of member accounts), projects, and resources.
A project is a container for TiDB Cloud resources.
- For TiDB Cloud Starter and Essential instances, a project is an optional logical container, which means you can either group these instances in a project or keep these instances at the organization level.
- For TiDB Cloud Dedicated clusters, a project is infrastructure-bound and required, which means TiDB Cloud Dedicated clusters must be grouped in projects for management purposes.
A resource in TiDB Cloud can be either a TiDB X instance (for example, TiDB Cloud Starter or TiDB Cloud Essential) or a TiDB Cloud Dedicated cluster.

If you are an organization owner, you can create multiple projects in your organization.

For TiDB X instances, you can either group them into projects or keep them directly at the organization level.
For TiDB Cloud Dedicated clusters, you must group them into projects.

The following is an example of the hierarchical structure:

- Your organization
    - TiDB X instances out of any project
        - TiDB Cloud Starter instance 1
        - TiDB Cloud Essential instance 1
    - TiDB X project 1
        - TiDB Cloud Starter instance 2
        - TiDB Cloud Starter instance 3
        - TiDB Cloud Essential instance 2
    - TiDB Dedicated project 1
        - TiDB Cloud Dedicated cluster 1
        - TiDB Cloud Dedicated cluster 2

Under this structure:

To access an organization, a user must be a member of that organization.
To access a project in an organization, a user must at least have the read access to the project in that organization.
To access a specific TiDB X instance, a user can be granted access through either a project role or an instance role.
To access a TiDB Cloud Dedicated cluster, a user must have the read access to the project in which the cluster is located.

For more information about user roles and permissions, see User Roles.

Organizations

An organization can contain multiple projects and TiDB X instances that are not grouped in any project.

TiDB Cloud calculates billing at the organization level and provides billing details for each project and resource.

If you are an organization owner, you have the highest permission in your organization.

For example, you can do the following:

Create different projects (such as development, staging, and production) for different purposes.
Assign different users with different organization roles, project roles, and instance roles.
Configure organization settings. For example, configure the time zone for your organization.

Projects

A project groups and manages TiDB Cloud resources.

In TiDB Cloud, there are three types of projects:

TiDB Dedicated project: This project type is used only for TiDB Cloud Dedicated clusters. It helps you manage settings for TiDB Cloud Dedicated clusters separately by project, such as RBAC, networks, maintenance, alert subscriptions, and encryption access.
TiDB X project: This project type is used only for TiDB X instances (TiDB Cloud Starter and TiDB Cloud Essential). It helps you manage RBAC for TiDB X instances by project. A TiDB X project is the default project type when you create a project on the My TiDB page.
TiDB X virtual project: This project is virtual and does not provide any management capabilities. It acts as a virtual container for TiDB X instances (TiDB Cloud Starter and TiDB Cloud Essential) that do not belong to any project, so these instances can be accessed through the TiDB Cloud API by using a project ID. Each organization has a unique virtual project ID. You can get this ID from the List all accessible projects endpoint of the TiDB Cloud API.

The following table lists the differences between these project types:

Feature	TiDB Dedicated Project	TiDB X Project	TiDB X Virtual Project
Project icon in the project view of the My TiDB page	(Folder icon with the letter D inside)	(Regular folder icon)	The project view displays TiDB X instances that are not assigned to any project in the Out of project list.
Resource type in the project	TiDB Cloud Dedicated clusters only	TiDB X instances only	TiDB X instances only
Project is optional	❌ (Each TiDB Cloud Dedicated cluster must belong to a Dedicated project)	✅ (You can either group a TiDB X instance in a TiDB X project or keep it at the organization level)	TiDB X instances that are not assigned to any project are automatically grouped into the TiDB X virtual project.
Project settings	✅	❌	❌
Infrastructure binding	✅ (Strong binding)	❌	❌
RBAC model	Organization -> Project	Organization -> Project -> Instance	Organization -> Project -> Instance
Project-level RBAC	✅	✅	❌
Project-level Billing	✅	✅	❌
Instance movement between TiDB X projects or the global scope	❌	✅	✅ (Global only)

User roles

TiDB Cloud defines different user roles to manage permissions at the organization, project, and instance levels.

You can grant roles to a user at the organization level, the project level, or the instance level. Make sure to carefully plan the hierarchy of your organizations, projects, and resources for security considerations.

Organization roles

At the organization level, TiDB Cloud defines five roles, in which Organization Owner can invite members and grant organization roles to members.

Permission	`Organization Owner`	`Organization Billing Manager`	`Organization Billing Viewer`	`Organization Console Audit Manager`	`Organization Viewer`
Manage organization settings, such as projects, API keys, and time zones.	✅	❌	❌	❌	❌
Invite users to or remove users from an organization, and edit organization roles of users.	✅	❌	❌	❌	❌
All the permissions of `Project Owner` for all projects in the organization, and all the permissions of TiDB X instance roles for all TiDB X instances in the organization.	✅	❌	❌	❌	❌
Create projects with Customer-Managed Encryption Key (CMEK) enabled.	✅	❌	❌	❌	❌
Edit payment information for the organization.	✅	✅	❌	❌	❌
View bills and use cost explorer.	✅	✅	✅	❌	❌
Manage TiDB Cloud console audit logging for the organization.	✅	❌	❌	✅	❌
View users in the organization and projects in which the member belong to.	✅	✅	✅	✅	✅

Note

The Organization Console Audit Manager role (renamed from Organization Console Audit Admin) is used to manage audit logging in the TiDB Cloud console, instead of database audit logging. To manage database auditing, use the Project Owner role at the project level.
The Organization Billing Manager role is renamed from Organization Billing Admin, and the Organization Viewer role is renamed from Organization Member.

Project roles

At the project level, TiDB Cloud defines four roles, in which Project Owner can invite members and grant project roles to members.

Note

Organization Owner has all the permissions of Project Owner for all projects so Organization Owner can invite project members and grant project roles to members too.
Each project role has all the permissions of Organization Viewer by default.
If a user in your organization does not belong to any projects, the user does not have any project permissions.
For both TiDB X projects and TiDB Dedicated projects, project roles control access to resources in the project. For TiDB Dedicated projects, project roles also control Dedicated-specific project settings.
Project roles do not apply to the TiDB X virtual project because TiDB X virtual project does not provide any management capabilities. To manage RBAC for a specific TiDB X instance that are not grouped in any TiDB X project, use instance roles.

Permission	`Project Owner`	`Project Data Access Read-Write`	`Project Data Access Read-Only`	`Project Viewer`
Manage project settings	✅	❌	❌	❌
Invite users to or remove users from a project, and edit project roles of users.	✅	❌	❌	❌
Manage database audit logging of the project.	✅	❌	❌	❌
Manage spending limit for all TiDB Cloud Starter instances in the project.	✅	❌	❌	❌
Manage resource operations in the project, such as creating, modifying, moving, and deleting instances or clusters supported by the project type.	✅	❌	❌	❌
Manage branches for TiDB Cloud Starter and TiDB Cloud Essential instances in the project, such as branch creation, connection, and deletion.	✅	❌	❌	❌
Manage resource data such as data import, data backup and restore, and data migration.	✅	✅	❌	❌
Manage Data Service for data read-only operations such as using or creating endpoints to read data.	✅	✅	✅	❌
Manage Data Service for data read and write operations.	✅	✅	❌	❌
View resource data using SQL Editor, if supported by the resource type.	✅	✅	✅	❌
Modify and delete resource data using SQL Editor, if supported by the resource type.	✅	✅	❌	❌
Manage changefeeds.	✅	✅	✅	❌
Review and reset resource passwords, if supported by the resource type.	✅	❌	❌	❌
View resource overview, backup records, metrics, events, and changefeeds in the project.	✅	✅	✅	✅

Instance roles

TiDB X instances support instance-level roles so that you can grant access to a single TiDB X instance without granting the same access to all resources in a project.

Note

Instance roles apply only to TiDB Cloud Starter and TiDB Cloud Essential. TiDB Cloud Dedicated clusters do not support instance roles.
Organization Owner automatically has all permissions for all TiDB X instances in the organization.
Each instance role inherits all the permissions of the Organization Viewer role by default.
Project roles and instance roles are additive. A user can inherit access from a project role and also have a more specific role on an individual instance.

Permission	`Instance Manager`	`TiDB X Instance Data Access Read-Write`	`TiDB X Instance Data Access Read-Only`	`TiDB X Instance Viewer`
Manage instance operations, such as instance creation, modification, and deletion.	✅	❌	❌	❌
View and modify instance data using SQL Editor.	✅	✅	❌	❌
View instance data using SQL Editor.	✅	✅	✅	❌
Manage instance-scoped roles.	✅	❌	❌	❌
View backup records of the TiDB X instance.	✅	❌	❌	✅
Restore the TiDB X instance from backups.	✅	❌	❌	❌
View instance overview.	✅	❌	❌	✅
View network settings.	✅	❌	❌	✅
View monitor and metrics.	✅	❌	❌	✅
View alerts.	✅	❌	❌	✅

Use project roles when you want to manage all resources in a project, and use instance roles when you want to grant access only to a specific TiDB X instance.

Manage organization access

View and switch between organizations

To view and switch between organizations, take the following steps:

In the TiDB Cloud console, click the combo box in the upper-left corner. The list of organizations you belong to is displayed.
Tip
- If you are currently on the page of a specific TiDB Cloud resource, after clicking the combo box in the upper-left corner, you also need to click Back to My TiDB in the combo box to return to the organization list.
- If you are a member of multiple organizations, you can click the target organization name in the combo box to switch your account between organizations.
To view the detailed information of your organization such as the organization ID and time zone, click the organization name, and then click Organization Settings > General in the left navigation pane.

Set the time zone for your organization

If you are in the Organization Owner role, you can modify the system display time according to your time zone.

To change the local timezone setting, take the following steps:

In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
In the left navigation pane, click Organization Settings > General.
In the Time Zone section, select your time zone from the drop-down list.
Click Update.

Invite a user to your organization

If you are in the Organization Owner role, you can invite users to your organization.

Note

You can also invite a user to your project or grant a user access to a TiDB X instance directly according to your need, which also makes the user your organization member.

To invite a user to your organization, take the following steps:

In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
In the left navigation pane, click Organization Settings > Users.
On the Users page, click Invite User in the upper-right corner.
Enter the email address of the user to be invited.
Tip
If you want to invite multiple members at one time, you can enter multiple email addresses.
(Optional) The invited user does not have any project or instance permissions by default. To grant project or instance roles to the user, do the following:
- To grant project-level access to the user, click Add Roles and Select Project, and then grant roles and select the target projects for the user.
- To grant access to a specific TiDB X instance to the user, click Add Roles and Select Instance, and then grant roles and select the target TiDB X instance for the user.
Click Invite. Then the new user is successfully added into the user list. At the same time, an email is sent to the invited email address with a verification link.
After receiving this email, the user needs to click the link in the email to verify the identity, and a new page shows.
If the invited email address has not been signed up for a TiDB Cloud account, the user is directed to the sign-up page to create an account. If the email address has been signed up for a TiDB Cloud account, the user is directed to the sign-in page, and after sign-in, the account joins the organization automatically.

Note

The verification link in the email expires in 24 hours. If the user you want to invite does not receive the email, click Resend.

Remove an organization member

If you are in the Organization Owner role, you can remove organization members from your organization.

To remove a member from an organization, take the following steps:

Note

If a member is removed from an organization, the member is also removed from all projects and loses all instance access in the organization.

In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
In the left navigation pane, click Organization Settings > Users.
On the Users page, locate the row of the target member, click ... in the row, and then click Delete.
In the confirmation dialog, click Delete.

Manage project access

This section describes how to rename a project and how to invite and remove project members. To learn how to create or manage a project, see Manage projects.

Rename a project

If you are in the Organization Owner role, you can rename any projects in your organization. If you are in the Project Owner role, you can rename your project.

To rename a project, take the following steps:

In the TiDB Cloud console, navigate to the My TiDB page of your organization, and then click the Project view tab.
Tip
If you are in multiple organizations, use the combo box in the upper-left corner to switch to your target organization first.
In the project view, locate the table of your target project, click ... in the upper-right corner of the table, and then click Rename.
Enter a new project name.
Click Confirm.

Invite a project member

If you are in the Organization Owner or Project Owner role, you can invite members to your projects.

Note

When a user not in your organization joins your project, the user automatically joins your organization as well.

To invite a member to a project, take the following steps:

In the TiDB Cloud console, navigate to the My TiDB page of your organization, and then click the icon to go to the project view.
Tip
If you are in multiple organizations, use the combo box in the upper-left corner to switch to your target organization first.
In the project view, locate the table of your target project, click ... in the upper-right corner of the table, and then click Invite.
In the displayed dialog, enter the email address of the user to be invited, and then select a project role for the user.
Tip
If you want to invite multiple members at one time, you can enter multiple email addresses.
Click Confirm. Then the new user is successfully added into the user list. At the same time, an email is sent to the invited email address with a verification link.
After receiving this email, the user needs to click the link in the email to verify the identity, and a new page shows.
If the invited email address has not been signed up for a TiDB Cloud account, the user is directed to the sign-up page to create an account. If the email address has been signed up for a TiDB Cloud account, the user is directed to the sign-in page. After sign-in, the account joins the project automatically.

Note

The verification link in the email will expire in 24 hours. If the invited user doesn't receive the email, click Resend.

Remove project access for a user

If you are in the Organization Owner or Project Owner role, you can remove project members.

To remove a member from a project, take the following steps:

In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
In the left navigation pane, click Organization Settings > Users.
On the Users page, locate the row of the target member, click ... in the row, and then click Edit Role.
On the Edit Role dialog, locate the target project, and then click the icon.
Click Save.

Manage instance access

Grant access to a TiDB X instance

If you are in the Organization Owner or Project Owner role, you can grant an instance role for a specific TiDB X instance to a user.

Note

Instance access applies only to TiDB X instances.

To grant access to a TiDB X instance, take the following steps:

In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
In the left navigation pane, click Organization Settings > Users.
On the Users page, locate the row of the target member, click ... in the row, and then click Edit Role.
Tip
If the user is not in your organization yet, click Invite User in the upper-right corner, and follow the steps in Invite a user to your organization to grant the instance role to the user.
On the Edit Role page, click Add Role and Select Instance in the Instance access section, and then grant roles and select the target TiDB X instance for the user.
Click Save.

Remove instance access for a user

If you are in the Organization Owner or Project Owner role, you can remove instance access for a user.

To remove instance access for a user, take the following steps:

In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
In the left navigation pane, click Organization Settings > Users.
On the Users page, locate the row of the target member, click ... in the row, and then click Edit Role.
On the Edit Role dialog, locate the target instance, and then click the icon.
Click Save.

Modify roles of a user

To modify a role of a user in TiDB Cloud, take the following steps:

In the TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
In the left navigation pane, click Organization Settings > Users.
On the Users page, locate the row of the target user, click ... in the row, and then click Edit Role.
- If you are in the Organization Owner role, you can modify organization roles, project roles, and instance roles of the target user.
- If you are in the Project Owner role, you can modify project roles and instance roles of the target user.
Click Save.

Manage user profiles

In TiDB Cloud, you can easily manage your profile, including your first name, last name, and phone number.

In the TiDB Cloud console, click in the lower-left corner.
Click Account Settings.
In the displayed dialog, update the profile information, and then click Update.

Identity Access Management

Organizations, projects, and resources

Organizations

Projects

User roles

Organization roles

Project roles

Instance roles

Manage organization access

View and switch between organizations

Set the time zone for your organization

Invite a user to your organization

Remove an organization member

Manage project access

Rename a project

Invite a project member

Remove project access for a user

Manage instance access

Grant access to a TiDB X instance

Remove instance access for a user

Modify roles of a user

Manage user profiles

Was this page helpful?