Manage service credentials (API keys)

Key features

• Service-level isolation: Each API Key is bound to a single cloud service (specified by its ServiceName) at creation. It can only be used to call the APIs of that service and cannot be used for cross-service calls. You cannot expand its scope with permission policies.

• Minimized permission scope: The effective permissions of an API Key are the intersection of the associated RAM user's permissions and the scope of the bound cloud service. Even if the RAM user has permissions for multiple services, the API Key remains restricted to its designated service.

• Restricted to RAM users: Only RAM users can create API Keys. Alibaba Cloud accounts (root accounts) cannot create them. This practice helps reduce the potential impact of a credential leak.

• Naming conventions: ServiceCredential is the term used in OpenAPI and SDKs, while the console uses the more user-friendly term API Key. Both terms refer to the same resource.

API Keys vs. AccessKeys

Both API Keys and AccessKeys are long-term credentials for RAM users. However, they differ in service scope, issuance methods, and use cases.

Lifecycle states

An API Key can be in one of the following three states during its lifecycle:

• Active: The credential can be used to call the OpenAPI of the bound cloud service. This is the default state upon creation.

• Inactive: The credential is temporarily disabled. You can reactivate it to the Active state. A key must be inactive before you can delete it.

• Expired: The system automatically changes the key's status to Expired when its expiration time is reached. The credential becomes permanently invalid and cannot be recovered. You must create a new key.

Quotas and expiration

• Quota: Each RAM user can create a maximum of two API Keys per cloud service, including both Active and Inactive keys. This quota is fixed. Expired keys count toward this quota; deleted keys do not.

• Expiration period unit: Days.

• Value range: The console provides presets for 1, 7, 30, and 90 days, or you can set a key to never expire. Custom values are also supported.

• OpenAPI default: If you omit the CredentialAgeDays parameter when calling the CreateServiceCredential operation, the key is set to never expire.

• Expiration is final: When a key expires, its status changes to Expired, and it becomes permanently invalid. It cannot be reactivated. You must delete the expired key and create a new one.

Supported cloud services

In the RAM console, go to the User Details page > Credential Management tab > API Keys section and click Create API Key. The Cloud Service dropdown list lists the services available to your account. Refer to the specific service's documentation for a list of supported APIs.

Self-management for RAM users

An Alibaba Cloud account or a RAM administrator with sufficient permissions can use the AllowUserToManageServiceCredential setting in the RAM security settings to control whether RAM users can manage their own API Keys. This setting has the following two states:

• Allow self-management: A RAM user can log on to the console or call OpenAPI to create, update, or delete their own API Keys, provided that these actions are not explicitly denied by an administrator in a permission policy (that is, no explicit Deny policy exists).

• Self-management not allowed: RAM users cannot manage their own API Keys. The keys must be created and maintained by an administrator who has permissions such as ram:CreateServiceCredential.

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ram:CreateServiceCredential",
        "ram:ListServiceCredentials"
      ],
      "Resource": "acs:ram:*:ACCOUNT_ID:user/USER_NAME"
    }
  ]
}

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ram:CreateServiceCredential",
        "ram:ListServiceCredentials",
        "ram:GetServiceCredential",
        "ram:UpdateServiceCredential",
        "ram:DeleteServiceCredential"
      ],
      "Resource": "acs:ram:*:ACCOUNT_ID:user/USER_NAME"
    }
  ]
}

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ram:CreateServiceCredential",
        "ram:ListServiceCredentials",
        "ram:GetServiceCredential",
        "ram:UpdateServiceCredential",
        "ram:DeleteServiceCredential"
      ],
      "Resource": "acs:ram:*:ACCOUNT_ID:user/USER_NAME",
      "Condition": {
        "StringEquals": {
          "ram:ServiceCredentialServiceName": "ak.aliyuncs.com"
        }
      }
    }
  ]
}

API Key data structure

Each API Key consists of the following core fields. The field names returned by OpenAPI are prefixed with ServiceCredential, while the field names in the console are more user-friendly.

Security recommendations

• Set an expiration period for API Keys. Avoid setting short-term test keys to never expire. For other use cases, set an appropriate expiration period, such as 30 or 90 days, based on the service's usage cycle and rotate the key before it expires.

• Immediately copy the API Key secret or download the CSV file after creating a key. Once you close the pop-up window, you cannot retrieve the secret again. If you lose the secret, you must delete the key and create a new one.

• Treat API Keys as highly sensitive credentials. Do not commit them in plaintext to code repositories, configuration files, or logs. We recommend using a secrets management service or encrypting them with KMS before storage.