API Keys

Contact Sales to Enable BYOC

API keys are used to authenticate users or applications making API or SDK calls to access Zilliz Cloud control plane and data plane resources. An API key is an alphanumeric string with its own properties, such as a name and an ID.

Overview of API keys

Zilliz Cloud offers two types of API keys to meet diverse user requirements:

• Personal API keys: Automatically generated upon user registration, each key is linked to the user’s account and inherits the privileges of the user’s role within the organization and project that the user belongs to. If the account user leaves the organization, the associated personal key is automatically deleted. As an Organization Owner or a Project Admin, you can see two types of personal API keys on the Zilliz Cloud web console:

  • Your own personal API key: A personal key that belongs exclusively to you. You can view and copy this API key.

  • Member's personal API key: A list of existing personal keys that belong to other users in the organization or project. You can only view the names and IDs of these keys but not the keys themselves.

• Customized API keys: Manually created by Organization Owners and Project Admins for applications or external users without Zilliz Cloud accounts. These keys are ideal for long-term access needs, ensuring service continuity even if the initial creator of the API key leaves the organization.

The following diagram illustrates API Key roles and resource access.

The table below details the access scope of API keys based on assigned roles. For more information about roles and privileges, see Access Control.

API Key Role		Access Level
Organization Owner		Full admin access to all resources within the organization, including projects and clusters.
Organization Billing Admin		Admin access to organization billing only. No access to projects and clusters within the organization.
Organization Member	Project Admin	Full admin access to specified projects and full admin access to all clusters within the projects by default.
	Project Read-Write	Read and write access to specified projects as well as read and write access to all clusters within the projects by default.
	Project Read-Only	Read-only access to specified projects as well as read-only access to all clusters within the projects by default.

Limits and restrictions

• Each organization can contain a maximum of 100 customized API keys.

• The management permissions for API keys are influenced by the user's roles within the organization and project. Specific permissions are outlined as follows:

  	Organization Owner	Organization Billing Admin	Organization Member
  			Project Admin	Project Read-Write	Project Read-Only
  Your Own Personal API Key
  Create	Auto generated	Auto generated	Auto generated	Auto generated	Auto generated
  View and copy	✔️	✔️	✔️	✔️	✔️
  Edit	✘	✘	✘	✘	✘
  Reset	✔️	✔️	✔️	✔️	✔️
  Delete	Auto deleted when user leaves the organization	Auto deleted when user leaves the organization	Auto deleted when user leaves the organization	Auto deleted when user leaves the organization	Auto deleted when user leaves the organization
  Members' Personal API Key
  Create	Auto generated	Auto generated	Auto generated	Auto generated	Auto generated
  View names and IDs	✔️	✘	✔️	✘	✘
  Copy	✘	✘	✘	✘	✘
  Edit	✘	✘	✘	✘	✘
  Reset	✘	✘	✘	✘	✘
  Delete	Auto deleted when member leaves the organization	Auto deleted when member leaves the organization	Auto deleted when member leaves the organization	Auto deleted when member leaves the organization	Auto deleted when member leaves the organization
  Customized API Key
  Create	✔️	✘	✔️	✘	✘
  View and copy	✔️	✘	✔️	✘	✘
  Edit	✔️	✘	✔️	✘	✘
  Reset	✔️	✘	✔️	✘	✘
  Delete	✔️	✘	✔️	✘	✘

Create an API key

Apart from personal keys that are automatically generated by Zilliz Cloud for each organization user, you can create customized keys. Only Organization Owners and Project Admins can create customized API keys.

1. Navigate to the organization's API Keys page. Click + API Key.

   

2. Enter the API Key Name and configure the API Key Access.

   

   • API Key Name: The name should not exceed 64 characters.

   • API Key Access: Define the access scope for the current customized API key by assigning the appropriate organization and project roles. For more fine-grained access control, you can limit the clusters that the key can access by checking Restrict Access to Specific Clusters.

     📘Notes

     For Project Admins, the permissions that this user can grant to an API key are limited to the user's own permission scope.

View API keys

Navigate to the organization's API Keys page. Your view may vary based on your specific role.

• As an Organization Owner, you can view your own personal key, all members' personal keys, and all customized keys.

• As a Project Admin, you can view your own personal key, members' personal keys and customized keys that fall within your permission scope. For example, if User 1 is only the Project Admin of Project A and Key 1 has Admin access to Projects A, B, and C, Key 1 will not be visible to User 1 since its access scope goes beyond User 1's permissions.

• As an Organization Billing Admin, a Project Read-Write, or a Project Read-Only, you can only view your own personal API key.

The screenshot below displays the Organization Owner's view of the API keys.

Edit an API key

Currently, you can only edit a customized API key. Personal keys cannot be edited because they are tied to an account user. To modify the access scope of a personal key, you need to first adjust the user's organization and project roles. Any changes to the user's role will automatically reflect in the key's access permissions.

The instructions below explains how to edit a customized API key.

1. Navigate to the organization's API Keys page. Click ... in the actions column and click Edit.

   

2. Edit the API Key API Key Name and the API Key Access.

   

   • API Key Name: The name should not exceed 64 characters.

   • API Key Access: Define the access scope for the current customized API key by assigning the appropriate organization and project roles. For more fine-grained access control, you can limit the clusters that the key can access by checking Restrict Access to Specific Clusters.

     📘Notes

     For Project Admins, the permissions that this user can grant to an API key are limited to the user's own permission scope.

Reset an API key

If you believe a personal or customized API key is compromised, you should immediately reset it.

🚧Warning

This operation will reset and invalidate the current API key. Any application code using this key will stop functioning until you update the relevant code with the new key value.

Depending on the type of key, the process varies:

• Reset personal API keys: you can reset your own personal API key only, regardless of your roles.

  

• Reset customized API keys: Only Organization Owners and Project Admins can reset customized API keys.

  

Delete an API key

If a customized API key is no longer in use, you should delete it as soon as possible. Only Organization Owners and Project Admins can delete customized API keys.

Personal key cannot be manually deleted. However, they will be automatically invalidated and removed when the corresponding user leaves the organization.

The following screenshots demonstrate how to delete a customized API key.

🚧Warning

Deleting an API key will irreversibly terminate access to Zilliz Cloud resources for any services using that key.