Creating an API Key

Function

The create API is the starting point for the API key lifecycle management process. It is designed to generate dedicated identity credentials for developers or workload systems. On the MaaS platform, model inference and data requests rely on valid keys for authentication. This API allows you to generate separate API keys for different scenarios and assign each key the minimum permissions required. This not only ensures isolation between workloads but also significantly reduces the risk of widespread service disruption caused by a single compromised key, helping safeguard the security and stability of model calls from the outset.

Constraints:

Authentication: Requests to this API must include a valid IAM token in the request header (X-Auth-Token) and have the corresponding fine-grained permission: modelarts:apiKey:create for creation.
Tenant Isolation: The scope of API operations is determined by the project/domain associated with the current token. The project_id is automatically populated from the authentication context. Cross-tenant operations are not supported.

Key security: The API key plaintext is returned only in the response to the API key creation request. All other APIs return only a masked value. Store the key securely immediately after creation. If it is lost, you must create a new one.

Ensure that the account has a sufficient balance; otherwise, the creation operation will fail.

URI

POST /v2/{project_id}/maas/api-auth/api-keys

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition: Project ID, which uniquely identifies tenant resources in Huawei Cloud and is associated with a specific region. It is used to locate the project space to which the resources belong when calling Huawei Cloud APIs. You can obtain the value by calling the API for obtaining a project ID and name. Constraints: N/A Range: N/A Default Value: N/A

Request Parameters

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
label	No	String	Definition: API key name. The tag can contain 0 to 100 characters, including letters, digits, underscores (_), and hyphens (-). Constraints: The value must be globally unique under a tenant. Range: N/A Default Value: If this parameter is not specified, the system generates a default value in the format of ak-{6-digit random number}.
description	No	String	Definition: Description of the API key. You can enter a maximum of 100 characters. Constraints: N/A Range: N/A Default Value: N/A
allow_all	Yes	Boolean	Definition: Specifies whether access is allowed from all IP addresses. Constraints: N/A Range: true: No IP address restrictions. false: Access is restricted by IP address. Default Value: N/A
ip_whitelist	No	Array of strings	Definition: The API key IP address whitelist is a security feature in Huawei Cloud Model as a Service (MaaS) that restricts the use of an API key to specified IP addresses when calling model services. This helps prevent unauthorized use if the API key is compromised. Examples: Single IP address (e.g., 192.168.1.1); IP address range (e.g., 192.168.1.10-192.168.1.100); CIDR block (e.g., 192.168.10.0/24). Constraints: Number of entries ≤ 100; Each IP address must be a valid IPv4 address. CIDR format is supported (e.g., 192.168.0.0/24); Duplicate IP addresses are not allowed; CIDR subnet masks must be valid and contiguous; This field must be empty when allow_all=true. IP address validation rules: IP octet validation: Each IPv4 octet must be a valid decimal integer between 0 and 255. IP address format and subnet mask validation: The overall format must match the regular expression for x.x.x.x or x.x.x.x/y. If a subnet mask is specified, its value must be between 0 and 32. Special rule: The subnet mask prefix length must be greater than or equal to the position of the rightmost 1 bit in the 32-bit binary representation of the IP address (that is, the mask must not truncate the IP address's significant bits). IP address comparison rule: To compare two IP addresses, compare their numerical values segment by segment from left to right (most significant to least significant) to determine their relative order. IP range validation: A valid IP range must contain exactly two IP addresses. Both addresses must pass the format and subnet mask validation rules described above, and the starting IP address must be less than or equal to the ending IP address.
resident_model_version_whitelist	No	ResidentModelVersionWhitelist object	Definition: Whitelist of resident model versions, which restricts the resident model versions that can be accessed. Constraints: N/A
endpoint_whitelist	No	EndpointWhitelist object	Definition: Whitelist of endpoints, which restricts the endpoints that can be accessed. Constraints: N/A

**Table 3** ResidentModelVersionWhitelist
Parameter	Mandatory	Type	Description
overall	No	String	Definition: Model service scope (including the model services and their versions) where the API key takes effect. Constraints: N/A Range: all: The API key takes effect for all model services. Empty string: The API key does not take effect for all model services. Default Value: Empty string.
whitelist	No	Array of Whitelist objects	Definition: Whitelist of resident model versions. Each entry specifies a resident model and its version that can be accessed. Range: Whitelist object array. For details, see the field breakdown below.

**Table 4** Whitelist
Parameter	Mandatory	Type	Description
resident_model_id	No	String	Definition: Resident model ID. The following uses the Chrome browser as an example to describe how to obtain the resident model ID: On the Real-Time Inference > Built-in Services page in the MaaS console, press F12 to open DevTools. Choose the Network tab and search for query. Click the entry whose name starts with query?business_type=payment. In the Response tab, search for the desired model name, such as DeepSeek-V4.1-Flash. The value of the resident_model_id parameter is the resident model ID. Constraints: N/A Range: N/A Default Value: N/A
version_whitelist	No	String	Definition: Whitelisted versions of the resident model that can be accessed. Separate multiple versions with commas (,). The following uses the Chrome browser as an example to describe how to obtain the resident model version name: On the Real-Time Inference > Built-in Services page in the MaaS console, press F12 to open DevTools. Choose the Network tab and search for query. Click the entry whose name starts with query?business_type=payment. In the Response tab, search for the desired model name, such as DeepSeek-V4.1-Flash. The ID of the data whose version_name is DeepSeek-V4.1-Flash under version_list is the resident model version. Constraints: N/A Range: N/A Default Value: N/A

**Table 5** EndpointWhitelist
Parameter	Mandatory	Type	Description
overall	No	String	Definition: Overall bypass policy. Constraints: N/A Range: The value "all" indicates that all requests are allowed to bypass. An empty string indicates that the overall bypass function is disabled. Default Value: Empty string.
whitelist	No	Array of strings	Definition: Whitelist of endpoint IDs. Only the endpoints in the whitelist can be accessed. You can obtain the ID by calling the API for querying endpoints. Constraints: N/A

Response Parameters

Status code: 201

**Table 6** Response body parameters
Parameter	Type	Description
id	String	Definition: Unique ID of an API key, which is automatically generated by the system. Range: N/A
api_key	String	Definition: Plaintext of the original API key generated by the inference service (returned only once during creation). A string of up to 255 characters. Range: N/A
label	String	Definition: Display name of the API key, which is the same as the label in the request. Range: N/A
description	String	Definition: Description of the API key, which is the same as the description in the request. A string of up to 100 characters. Range: N/A
allow_all	Boolean	Definition: Specifies whether access is allowed from all IP addresses. Range: true: No IP address restrictions. false: Access is restricted by IP address.
ip_whitelist	Array of strings	Definition: IP address whitelist. The effective value is displayed in the command output. Range: N/A
resident_model_version_whitelist	ResidentModelVersionWhitelist object	Definition: Whitelist information of the resident model version, which is the same as the value in the request. Range: N/A
endpoint_whitelist	EndpointWhitelist object	Definition: Whitelist information of the endpoint, which is the same as the value in the request. Range: N/A

**Table 7** ResidentModelVersionWhitelist
Parameter	Type	Description
overall	String	Definition: Model service scope (including the model services and their versions) where the API key takes effect. Range: all: The API key takes effect for all model services. Empty string: The API key does not take effect for all model services.
whitelist	Array of Whitelist objects	Definition: Whitelist of resident model versions. Each entry specifies a resident model and its version that can be accessed. Range: Whitelist object array. For details, see the field breakdown below.

**Table 8** Whitelist
Parameter	Type	Description
resident_model_id	String	Definition: Resident model ID. The following uses the Chrome browser as an example to describe how to obtain the resident model ID: On the Real-Time Inference > Built-in Services page in the MaaS console, press F12 to open DevTools. Choose the Network tab and search for query. Click the entry whose name starts with query?business_type=payment. In the Response tab, search for the desired model name, such as DeepSeek-V4.1-Flash. The value of the resident_model_id parameter is the resident model ID. Range: N/A
version_whitelist	String	Definition: Whitelisted versions of the resident model that can be accessed. Separate multiple versions with commas (,). The following uses the Chrome browser as an example to describe how to obtain the resident model version name: On the Real-Time Inference > Built-in Services page in the MaaS console, press F12 to open DevTools. Choose the Network tab and search for query. Click the entry whose name starts with query?business_type=payment. In the Response tab, search for the desired model name, such as DeepSeek-V4.1-Flash. The ID of the data whose version_name is DeepSeek-V4.1-Flash under version_list is the resident model version. Range: N/A

**Table 9** EndpointWhitelist
Parameter	Type	Description
overall	String	Definition: Overall bypass policy. Range: The value "all" indicates that all requests are allowed to bypass. An empty string indicates that the overall bypass function is disabled.
whitelist	Array of strings	Definition: Whitelist of endpoint IDs. Only the endpoints in the whitelist can be accessed. You can obtain the ID by calling the API for querying endpoints.

Status code: 403

**Table 10** Response body parameters
Parameter	Type	Description
error_msg	String	Definition: Error message. Range: N/A
error_code	String	Definition: Error code. Range: N/A

Example Requests

POST https://{endpoint}/v2/{project_id}/services/api-auth/api-keys/

{
  "description" : "Key used for calls in the production environment.",
  "label" : "my-api-key",
  "allow_all" : false,
  "ip_whitelist" : [ "192.168.0.0/24", "10.0.0.1" ],
  "resident_model_version_whitelist" : {
    "overall" : "",
    "whitelist" : [ {
      "resident_model_id" : "ce15e584-bb43-46ff-a215-febb27501353",
      "version_whitelist" : "all"
    }, {
      "resident_model_id" : "1a848aa4-6493-4da0-bd5a-e1e918fad55f",
      "version_whitelist" : "all"
    } ]
  },
  "endpoint_whitelist" : {
    "overall" : "",
    "whitelist" : [ "d8d76767-637a-4040-8835-39bdc39b79b6", "6a9cba80-3594-4611-a8c0-a5a1fd34985d" ]
  }
}

Example Responses

Status code: 201

{
  "id" : "1ccb3e8f-ece2-4f9c-97cc-18143dff685c",
  "api_key" : "Returned plaintext API key.",
  "label" : "my-api-key",
  "description" : "Key used for calls in the production environment.",
  "allow_all" : false,
  "ip_whitelist" : [ "192.168.0.0/24", "10.0.0.1" ],
  "resident_model_version_whitelist" : {
    "overall" : "",
    "whitelist" : [ {
      "resident_model_id" : "ce15e584-bb43-46ff-a215-febb27501353",
      "version_whitelist" : "all"
    }, {
      "resident_model_id" : "1a848aa4-6493-4da0-bd5a-e1e918fad55f",
      "version_whitelist" : "all"
    } ]
  },
  "endpoint_whitelist" : {
    "overall" : "",
    "whitelist" : [ "d8d76767-637a-4040-8835-39bdc39b79b6", "6a9cba80-3594-4611-a8c0-a5a1fd34985d" ]
  }
}

Status code: 403

{
  "error_msg" : "Invalid token.",
  "error_code" : "ModelArts.0104"
}

Status Codes

Status Code	Description
201	The API key is created.
403	The user authentication token is abnormal.

Error Codes

See Error Codes.

Parent Topic: API Key Authentication Management

Previous topic: API Key Authentication Management

Next topic: Updating an API Key