API Keys
On Zilliz Cloud, every organization comes with a set of API keys. These keys are essential authentication tokens required for initiating RESTful API or SDK calls. They play a crucial role in accessing specific projects and resources within the organization.
Overview of API keys
To cater to various requirements, Zilliz Cloud offers two distinct types of API keys:
-
Personal keys: Linked to individual users, this type of key is auto-generated by Zilliz Cloud for each organization user, inheriting the permissions of the user role. If the user leaves the organization, its personal key will be automatically deleted, which might not be ideal for long-term projects.
-
Customized keys: Tied to applications or programs, rather than individual users. Users with Owner status can create and oversee this type of key. Customized keys are suitable for development purposes, offering stable, long-term API integration and automation capabilities.
In versions released prior to January 16, 2024, API key types weren't categorized. If you upgrade your Zilliz Cloud service from a version released before this date, your API keys generated earlier will be designated as customized API keys. These keys will inherit the project-level permissions of the original API keys.
Secure API calls with RBAC
Role-based Access Control (RBAC) is a crucial security mechanism in Zilliz Cloud, applicable to managing API calls. This system allows for fine-grained control over access to resources by assigning roles with specific permissions to users within the organization.
For more information on access levels of each role, see Authorization.
API key management
User roles within an organization affect the extent of API key management permissions. The specific permissions are outlined as follows:
| Organization Owner | Project Owner | Project Member | |
|---|---|---|---|
| Personal API Key | |||
| Creation | Auto generated | Auto generated | Auto generated |
| Viewing the user's assigned API key | ✔️ | ✔️ | ✔️ |
| Viewing member's API key names [1] | ✔️ | ✔️ | ✘ |
| Resetting API key [2] | ✔️ | ✔️ | ✔️ |
| Customized API Key | |||
| Creation | ✔️ | ✔️ [3] | ✘ |
| Viewing | ✔️ | ✔️ [4] | ✘ |
| Removing permissions from API key | ✔️ | ✔️ [4] | ✘ |
| Editing API key name | ✔️ | ✘ | ✘ |
| Resetting API key | ✔️ | ✘ | ✘ |
| Deleting API key | ✔️ | ✘ | ✘ |
Notes:
[1] Owner users can view member's API key names based on their permission scope. Organization owners can view all member's API key names organization-wide, while project owners can only view those within their permission range. Project members can only view their own personal key.
[2] Each user can reset only their own personal key.
[3] The permission that a project owner can grant to a customized API key is subject to its own permission scope.
[4] Project owners can only view or manage customized API keys within their permission scope. For example, if User 1 owns Project A and a customized API key (Key 1) has access to Projects A, B, and C, User 1 has no access to Key 1 since its access scope goes beyond User 1's permissions.
Create an API key
Apart from personal keys that are automatically generated by Zilliz Cloud for each organization user, you can create customized keys. For long-term projects or application development, it's recommended to use a customized API key, rather than a personal one.
Each Organization Owner or Project Owner has the permission to create a customized API key. An essential step of creating an API key is defining its access scope, where you'll decide which projects and clusters the API key can access.
- API Key Access: Define the access scope for the current customized API key by assigning the appropriate organization role, specifying the target project the key can access, and setting the key's role within that project. For more fine-grained access control, you can limit the clusters that the key can access by setting up a whitelist in Restrict Access to Specific Clusters.
You can add more projects in API Key Access.
For Project Owners creating a customized API key, the permissions you can grant are limited to your own permission scope. This ensures that each API key's capabilities align with the responsibilities and roles of its creator, maintaining a secure and controlled environment.
With a customized API key in hand, you can now establish connections to a cluster to which the API key has access. See Connect to Cluster to explore further details.
View API keys
To view API keys created in an organization, you must hold the role of either an Organization Owner or a Project Owner.
-
Personal keys: Organization or Project Owners have the privilege to see the names of member's API keys generated for users within the organization. However, they will not have access to the actual values of these personal API keys, ensuring user privacy and security.
-
Customized keys: Organization Owners can view all customized API keys created within the organization. If you are a Project Owner, you can view only the API keys with the access scopes falling within your own. This means you can only access the API keys that are relevant to your project and within your administrative reach.
Edit an API key
As an Organization Owner or a Project Owner, you can edit an API key to rename it or modify its access permissions.
-
Rename the customized key: Only Organization Owners have the privilege to rename a customized API key.
-
Modify access permissions: As an Organization Owner, you have the privilege to update the permissions of an API key in any capacity. If you are a Project Owner, your ability to modify API key permissions is restricted to the scope of permissions you already hold. This means as a Project Owner, you cannot extend permissions to a higher level than your current access allows, ensuring no permission escalation occurs.
Only customized API keys can be edited.
Reset an API key
Resetting an API key is critical in maintaining the security and integrity of access control. Depending on the type of key, the process varies:
-
Personal keys: Each organization user can reset their own personal API key only, regardless of their roles. This ensures that users can promptly respond to any security concerns or access issues by generating a new key, maintaining a secure and personalized access system.
-
Customized keys: Resetting customized API keys is exclusively reserved for Organization Owners. This level of control is crucial in managing broader, organization-wide access and security. Organization Owners can reset these keys to address security issues or update access protocols, ensuring that the integrity of application-level access remains uncompromised.
This operation will reset and invalidate the current API key. Any custom code using this key will stop functioning until you update the relevant code with the new key.
Delete an API key
If an API key is no longer needed, you can delete it as an Organization Owner.
Only customized API keys can be deleted. Personal keys can be reset by their own user, but cannot be deleted.
Exercise caution when deleting an API key. Doing so will immediately revoke access to any resources that were using the key.
