# cas-certificate

Part of **CAS**

<!-- intent-backlink:auto -->

> 💡 **Path Selection**: This skill is one implementation path for the following routing skills. If you're unsure which path to take, check the corresponding routing skill:

> - [Deploy SSL certificate to servers or cloud resources](../../intent/cas-deploy-certificate/SKILL.md)
> - [Apply for an SSL/TLS certificate](../../intent/cas-apply-certificate/SKILL.md)
> - [Manage private CA and private certificates](../../intent/cas-manage-certificates/SKILL.md)
> - [Troubleshoot SSL/TLS certificate issues](../../intent/cas-troubleshoot-issues/SKILL.md)

# Certificate Management Service Certificate Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Manage Certificates | Synchronous | Perform general certificate lifecycle operations including listing, retrieving details, and managing certificate orders. |
| Create Certificate Request | Synchronous | Submit requests to issue new certificates, including from packages or with CSR. |
| Manage Certificate Signing Requests (CSR) | Synchronous | Create, upload, list, and manage certificate signing requests. |
| Manage Client Certificates | Synchronous | Create, list, describe, and revoke client certificates. |
| Manage CA Certificates | Synchronous | Create, list, describe, and manage root, sub-CA, and external CA certificates. |
| Manage Certificate Warehouse | Synchronous | Create, delete, list, and query certificate warehouses and their quotas. |
| Manage Deployment Jobs | Synchronous | Create, update, delete, and monitor certificate deployment jobs to cloud resources. |
| Manage Encryption Operations | Synchronous | Perform encryption, decryption, signing, and verification using certificates. |
| Manage Resource Groups and Tags | Synchronous | Move certificates between resource groups and manage resource tagging. |
| Cancel and Refund Orders | Synchronous | Cancel pending certificate orders and request refunds. |

## Authentication

Use Bearer Token authentication for all Certificate Management Service API calls.

- **Header format**: `Authorization: Bearer <your_api_key>`
- **Environment variable**: `DASHSCOPE_API_KEY`

Set your API key as an environment variable and include it in the Authorization header of all requests.

## Service Endpoint

Certificate Management Service APIs use region-specific endpoints:

- **Base URL pattern**: `https://cas.{region}.aliyuncs.com`
- **Common regions**: 
  - China: `cn-hangzhou`, `cn-shanghai`, `cn-beijing`
  - International: `ap-southeast-1`, `cn-shanghai`, `eu-central-1`

For global operations, you can also use:
- China site: `https://api.aliyun.com/api/cas/2020-04-07/`
- International site: `https://api.alibabacloud.com/api/cas/2020-04-07/`

## Parameter Reference

### Manage Certificates

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| KeyWord | string | false | | | The keyword for a fuzzy search by name, domain name, or subject alternative name. |
| WarehouseId | integer | false | | | The warehouse ID. You can obtain this ID by calling the ListCertWarehouse API. |
| Status | string | false | | one of: ISSUE, REVOKE | The certificate status. Valid values: ISSUE (issued), REVOKE (revoked). |
| SourceType | string | false | | one of: upload, aliyun | The source of the certificate. Valid values: upload (uploaded certificate), aliyun (Alibaba Cloud certificate). |
| CertType | string | false | | one of: CA, CERT | The certificate type. Valid values: CA (CA certificate), CERT (issued certificate). |
| CurrentPage | integer | false | 1 | | The page number to return. The default value is 1. |
| ShowSize | integer | false | 50 | | The number of entries per page. The default value is 50. |
| Identifiers | string | false | | | A comma-separated list of certificate identifiers. |
| CertificateId | integer | true | | | The certificate ID. |
| InstanceUuid | string | false | | | The UUID of the instance. |
| BeforeDate | string | false | | | Filters certificates modified before this date. |
| AfterDate | string | false | | | Filters certificates modified after this date. |
| Type | string | false | | one of: SERVER, CLIENT, END_ENTITY | The certificate type. Valid values: SERVER (Server certificate), CLIENT (Client certificate), END_ENTITY (End-entity certificate). |
| MaxResults | integer | false | | | The maximum number of entries to return. |
| NextToken | string | false | | | The token used to retrieve the next page of results. |

### Create Certificate Request

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| ProductCode | string | false | digicert-free-1-free | | The certificate specifications. Valid values include various DigiCert, Symantec, GeoTrust, and GlobalSign certificate types. |
| Username | string | true | | | The name of the applicant. |
| Phone | string | true | | | The phone number of the applicant. |
| Email | string | true | | | The contact email address of the applicant. |
| Domain | string | true | | | The domain name to bind to the certificate. Only one domain name is allowed. |
| ValidateType | string | true | | one of: DNS, FILE | The method to verify domain name ownership. Valid values: DNS, FILE. |
| Csr | string | true | | | The content of the CSR file. The key algorithm must be RSA or ECC. |
| Years | integer | false | | | The validity period of the certificate, in years. |
| Months | integer | false | | | The validity period of the certificate, in months. |
| Days | integer | false | | | The validity period of the server certificate, in days. |
| BeforeTime | integer | false | current time | | Issue time of the server certificate, in UNIX timestamp format. |
| AfterTime | integer | false | | | Expiration time of the server certificate, in UNIX timestamp format. |
| Organization | string | false | Alibaba Inc. | | The name of the organization. |
| OrganizationUnit | string | false | Alibaba Cloud CDN | | The name of the department. |
| Country | string | false | | | The country code, such as CN or US. |
| CommonName | string | false | | | Set the common name for the certificate. |
| State | string | false | | | Set the name of the province, municipality, or autonomous region. |
| Locality | string | false | | | The city where the organization for the certificate is located. |
| Algorithm | string | false | | one of: RSA_1024, RSA_2048, RSA_4096, ECC_256, ECC_384, ECC_512, SM2_256 | Key algorithm for the server certificate. |
| ParentIdentifier | string | true | | | Unique identifier of the subordinate CA certificate that issues this certificate. |
| Immediately | integer | false | 0 | one of: 0, 1, 2 | Specifies whether to return the digital certificate immediately. |
| EnableCrl | integer | false | | one of: 0, 1 | Specifies whether to include the certificate revocation list (CRL) address. |
| Tags | array<object> | false | | | A list of tags. |
| ResourceGroupId | string | false | | | The ID of the resource group. |
| CustomIdentifier | string | false | | | A custom identifier. This is a unique key. |

### Manage Certificate Signing Requests (CSR)

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| Algorithm | string | true | | one of: RSA, ECC, SM2 | The encryption algorithm. Valid values: RSA, ECC, SM2. |
| KeySize | integer | true | | RSA: 2048, 3072, 4096; ECC/SM2: 256 | The key size used by the algorithm. |
| CommonName | string | true | | max length: 253 characters | The primary domain name (common name) of the certificate. |
| Sans | string | false | | max 100 domains | The subject alternative names (SANs). Separate multiple domain names with commas (,). |
| CountryCode | string | true | | two-letter ISO 3166-1 alpha-2 code | The two-letter country or region code of the organization. |
| Province | string | true | | max length: 128 characters | The province or state where the organization is located. |
| Locality | string | true | | max length: 128 characters | The city where the organization is located. |
| CorpName | string | false | | max length: 255 characters | The name of the organization. |
| Department | string | false | | max length: 255 characters | The department within the organization that uses the certificate. |
| Name | string | false | | max length: 50 characters | The name of the CSR. |
| CsrId | integer | true | | | The ID of the CSR. |
| Key | string | true | | | The content of the certificate private key in PEM format. |

### Manage Client Certificates

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| SanType | integer | false | | | The type of the subject alternative name (SAN) for the client certificate. Valid values: 1 (email address), 2 (domain name), 6 (URI), 7 (IP address). |
| SanValue | string | false | | | The value of the SAN extension. To specify multiple values, separate them with commas (,). |
| CommonName | string | false | | | The common name of the client certificate. |
| Algorithm | string | false | | | The key algorithm for the client certificate. |
| Csr | string | false | | | The content of the certificate signing request (CSR). |
| ParentIdentifier | string | true | | | The unique identifier of the issuing subordinate CA certificate. |
| Days | integer | false | | | The validity period of the client certificate, in days. |
| BeforeTime | integer | false | | | The issuance time of the client certificate, as a Unix timestamp in seconds. |
| AfterTime | integer | false | | | The expiration time of the client certificate, specified as a Unix timestamp in seconds. |
| Organization | string | false | | | The organization name associated with the root CA certificate. |
| OrganizationUnit | string | false | | | The name of the department or business unit within the organization. |
| Country | string | false | | | The country where the organization is located. |
| State | string | false | | | The province, municipality, or autonomous region where the organization is located. |
| Locality | string | false | | | The city where the organization is located. |
| Years | integer | false | | | The validity period of the certificate, in years. |
| Months | integer | false | | | The validity period of the certificate, in months. |
| Immediately | integer | false | | | Specifies which certificate content to return in the response. |
| Identifier | string | true | | | The unique identifier of the client or server certificate to revoke. |

### Manage CA Certificates

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| CommonName | string | true | | | The common name or abbreviation of the organization. |
| OrganizationUnit | string | true | | | The name of the department or branch in the organization. |
| Organization | string | true | | | The name of the organization for the root CA certificate. |
| Locality | string | true | | | The name of the city where the organization is located. |
| State | string | true | | | The name of the province or state where the organization is located. |
| CountryCode | string | false | | valid values: two-letter uppercase ISO country codes (e.g., CN, US) | The two-letter uppercase code of the country or region. |
| Algorithm | string | false | | one of: RSA_1024, RSA_2048, RSA_4096, ECC_256, ECC_384, ECC_512, SM2_256 | The key algorithm of the root CA certificate. |
| Years | integer | true | | range: 5-10 | The validity period of the root CA certificate. Unit: years. |
| ClientToken | string | false | | ASCII characters only | A client token to ensure the idempotence of the request. |
| ResourceGroupId | string | false | | | The ID of the resource group. |
| CertIdentifier | string | false | | | The unique identifier of the certificate. |
| InstanceId | string | false | | | The ID of the private CA instance to query. |

### Manage Certificate Warehouse

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| Name | string | false | | | The name of the certificate warehouse. |
| Type | string | false | | one of: uploadedAuthorityCertificate, pcaCertificate, uploadedCertificate, personal, ssl, pcaAuthorityCertificate | The type of the certificate warehouse. |
| Biz | string | false | | | The use case of the certificate warehouse. |
| WarehouseInstanceId | string | true | | | The certificate warehouse instance ID. |
| WarehouseInstanceIds | array | false | | | A list of warehouse instance IDs. |
| WarehouseTypes | array | false | | | A list of warehouse types. |
| NextToken | string | false | | | The pagination token from a previous response. |
| MaxResults | integer | false | 20 | default value is 20 | The maximum number of entries to return on each page. |

### Manage Deployment Jobs

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| Name | string | true | | | The name of the deployment job. |
| JobType | string | true | | one of: cloud, user | The type of the deployment job. |
| CertIds | string | true | | | The IDs of the certificates to deploy, separated by commas (,). |
| ResourceIds | string | true | | | The IDs of the target cloud resources, separated by commas (,). |
| ContactIds | string | true | | | The IDs of the contacts to notify, separated by commas (,). |
| ScheduleTime | integer | false | | | The scheduled start time for the job, as a UNIX timestamp. |
| JobId | integer | true | | | The ID of the deployment task. |
| SecretId | string | false | | | The AccessKey ID that is used to access cloud resources. |

### Manage Encryption Operations

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| CertIdentifier | string | false | | | The unique identifier of the certificate. |
| Algorithm | string | true | | one of: RSAES_OAEP_SHA_1, RSAES_OAEP_SHA_256, SM2PKE | The encryption algorithm. |
| CiphertextBlob | string | true | | | The Base64-encoded data to decrypt. |
| MessageType | string | false | Base64 | one of: RAW, Base64 | The message type. |
| CustomIdentifier | string | false | | | A custom identifier that serves as a unique key. |
| WarehouseId | integer | false | | | The ID of the repository. |
| Plaintext | string | true | | | The data to encrypt. |
| SigningAlgorithm | string | true | | one of: SHA256withRSA, SHA256withRSA/PSS, SHA256withECDSA, SM3withSM2, SHA256withRSA/P7 | The signature algorithm. |
| Message | string | true | | | The data to sign. |
| SignatureValue | string | true | | | The signature value. Must be Base64-encoded. |

### Manage Resource Groups and Tags

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| ResourceId | string | true | | | The ID of the resource. |
| ResourceGroupId | string | true | | | The ID of the resource group. |
| ResourceType | string | true | instance | one of: instance, Certificate | The type of the resource. |
| RegionId | string | false | | one of: ap-southeast-1, cn-hangzhou | The region of the organization to which the owner of the certificate belongs. |
| All | boolean | false | false | one of: true, false | Specifies whether to remove all tags from the resource. |
| TagKey | array | false | | | The tag keys. |

### Cancel and Refund Orders

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| OrderId | integer | true | | | The ID of the certificate application order to delete. |
| InstanceId | string | true | | | The ID of the instance. |

## Code Examples

### List Certificates - Python - All Regions

```python
import requests
import json

# Set up the API endpoint and headers
url = "https://api.aliyun.com/api/cas/2020-04-07/ListCert"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request parameters
params = {
    "KeyWord": "test",
    "ShowSize": 10,
    "CurrentPage": 1
}

# Make the API call
response = requests.get(url, headers=headers, params=params)

# Parse the response
if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### Create Certificate Request - Python - All Regions

```python
import dashscope

# Set your API key
dashscope.api_key = 'your-api-key'

# Define the request parameters
params = {
    'ProductCode': 'symantec-free-1-free',
    'Username': 'Tom',
    'Phone': '1390000****',
    'Email': 'username@example.com',
    'Domain': 'www.aliyundoc.com',
    'ValidateType': 'DNS'
}

# Call the API
response = dashscope.CertificateManagementService.create_certificate_request(**params)

# Print the response
print(response)
```

### Get Certificate Details - Python - All Regions

```python
import requests
import json

# Set up the API endpoint and headers
url = "https://api.aliyun.com/api/cas/2020-04-07/GetUserCertificateDetail"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request parameters
params = {
    "CertId": 6055048,
    "CertFilter": False
}

# Make the API call
response = requests.get(url, headers=headers, params=params)

# Parse the response
if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### List User Certificate Orders - Python - All Regions

```python
import json
import requests

# Set up the API endpoint
url = "https://api.aliyun.com/api/cas/2020-04-07/ListUserCertificateOrder"

# Set up headers with your API key
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Define the request parameters
params = {
    "OrderType": "CERT",
    "Status": "ISSUED",
    "CurrentPage": 1,
    "ShowSize": 50
}

# Make the API call
response = requests.get(url, headers=headers, params=params)

# Parse and print the response
if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### Create CSR - Python - All Regions

```python
import dashscope

# Set your API key
dashscope.api_key = 'your-api-key'

# Define the request parameters
params = {
    'Algorithm': 'RSA',
    'KeySize': 2048,
    'CommonName': '123.com',
    'CountryCode': 'CN',
    'Province': 'Beijing',
    'Locality': 'Beijing',
    'Name': 'csr-123'
}

# Call the API
response = dashscope.certificate_management.create_csr(params)

# Print the response
print(response)
```

### Describe Client Certificate - Python - All Regions

```python
import json
import requests

# Set up the API endpoint and headers
url = "https://cas.aliyuncs.com/api/v1/DescribeClientCertificate"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Define the request body
payload = {
    "Identifier": "d3b95700998e47afc4d95f886579****"
}

# Make the API call
response = requests.post(url, headers=headers, data=json.dumps(payload))

# Parse and print the response
if response.status_code == 200:
    result = response.json()
    print(json.dumps(result, indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")
```

### Encrypt Data - JSON - All Regions

```json
{
  "CertIdentifier": "1ef1da5f-38ed-69b3-****-037781890265",
  "RequestId": "5979d897-d69f-4fc9-87dd-f3bb73c40b80",
  "CiphertextBlob": "ZOyIygCyaOW6Gj****MlNKiuyjfzw="
}
```

### Describe CA Certificate List - Python - All Regions

```python
import requests
import json

# Set your API endpoint and headers
url = "https://cas.aliyuncs.com/api/v1/DescribeCACertificateList"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request parameters
params = {
    "CurrentPage": 1,
    "ShowSize": 20
}

# Make the request
response = requests.get(url, headers=headers, params=params)

# Parse response
if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")
```

## Response Format

```json
{
  "ShowSize": 50,
  "CurrentPage": 1,
  "TotalCount": 10,
  "CertList": [
    {
      "WhId": 2,
      "Identifier": "14dcc8afc7578e",
      "WhInstanceId": "test_whInstanceId",
      "Status": "ISSUE",
      "SourceType": "aliyun",
      "CertType": "CERT",
      "CommonName": "aliyun.alibaba.com",
      "BeforeDate": 1665819958000,
      "Issuer": "mySSL",
      "AfterDate": 1634283958000,
      "ExistPrivateKey": false,
      "Sans": "*.alibaba.com,aliyun.alibaba.com",
      "SerialNo": "",
      "Algorithm": "",
      "SignAlgorithm": ""
    }
  ],
  "RequestId": "15C66C7B-671A-4297-9187-2C4477247A74"
}
```

**Key Fields**:
- `ShowSize` — Number of entries per page
- `CurrentPage` — Current page number
- `TotalCount` — Total number of certificates matching the query
- `CertList[].WhId` — Warehouse ID
- `CertList[].Identifier` — Certificate identifier
- `CertList[].Status` — Certificate status (ISSUE, REVOKE)
- `CertList[].SourceType` — Source of the certificate (upload, aliyun)
- `CertList[].CertType` — Certificate type (CA, CERT)
- `CertList[].CommonName` — Primary domain name
- `CertList[].BeforeDate` — Certificate issuance timestamp
- `CertList[].AfterDate` — Certificate expiration timestamp
- `CertList[].ExistPrivateKey` — Whether private key exists
- `CertList[].Sans` — Subject Alternative Names
- `RequestId` — Unique request identifier for troubleshooting

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|-------------------|
| 429 | Too many requests. The single-user QPS limit for this API is 10. Calls exceeding this limit are throttled, which may impact your business. Plan your API calls accordingly. | Reduce your request rate to stay under the QPS limit. Implement exponential backoff for retries. |
| 403 | Access denied. Ensure that the RAM policy includes the yundun-cert:GetUserCertificateDetail permission. | Verify your RAM user/role has the required permissions for the specific API operation. |
| InvalidParameter.CertId | The specified CertId parameter is invalid or does not exist. | Check that the certificate ID is correct and exists in your account. |
| Throttling | Rate limit exceeded. The QPS limit is 10 calls per second per user. If exceeded, API calls are throttled. | Implement rate limiting in your application to stay within the 10 QPS limit per user. |
| UnauthorizedOperation | The request is not authorized. Ensure that the RAM policy includes the yundun-cert:ListUserCertificateOrder permission. | Confirm your credentials have the necessary permissions for the requested operation. |

### Rate Limits & Retry

- **Standard APIs**: 10 QPS per user for most certificate management operations
- **Certificate details APIs**: 100 QPS per user for GetUserCertificateDetail
- **Encryption operations**: 10 QPS per user for cryptographic operations

When you receive a 429 error, implement exponential backoff with jitter. Start with a 1-second delay and double the delay with each retry, up to a maximum of 30 seconds.

## Environment Requirements

- **API Key**: Set your API key in the `DASHSCOPE_API_KEY` environment variable
- **Authentication**: Include `Authorization: Bearer $DASHSCOPE_API_KEY` in request headers
- **Python**: Use the `requests` library for HTTP calls or `dashscope` SDK for higher-level operations
- **Rate Limits**: Respect the QPS limits (10-100 QPS depending on the API)

## FAQ

Q: How do I authenticate API requests to Certificate Management Service?
A: Use Bearer Token authentication by setting the `Authorization: Bearer YOUR_API_KEY` header. Store your API key in the `DASHSCOPE_API_KEY` environment variable.

Q: What's the difference between ListCert and ListUserCertificateOrder APIs?
A: ListCert queries certificates in your certificate store with filtering options, while ListUserCertificateOrder queries SSL certificates and certificate orders with support for order types and statuses.

Q: How can I handle rate limiting when making multiple API calls?
A: Most Certificate Management APIs have a 10 QPS limit per user. Implement rate limiting in your application and use exponential backoff when you receive 429 errors.

Q: Can I create certificates without providing my own CSR?
A: Yes, several APIs like CreateServerCertificate and CreateClientCertificate can generate CSRs automatically. You only need to provide certificate details like domain name, organization info, and validity period.

Q: How do I retrieve both the certificate and private key?
A: Use the GetUserCertificateDetail API with CertFilter set to false (default). This returns both the certificate content and private key in the response.

## Pricing & Billing

### Billing Model
The Certificate Management Service uses a per-request billing model for API calls, with additional charges for certificate purchases.

### Price Reference

| Tier | Input Price | Output Price | Other Fees |
|------|-------------|--------------|------------|
| ListCert | 0.002 / | 0.002 / |
| GetUserCertificateDetail | 0.001 / | 0.001 / |
| ListUserCertificateOrder | 0.001 / | 0.001 / |
| CreateCertificateRequest (free tiers) | 0 / | 0 / | Free for 3-12 months depending on product |
| CreateCertificateRequest (paid tiers) | 10-250 / | 10-250 / | One-time charge per certificate |
| CreateCsr | 0.001 / | |
| Encrypt/Decrypt | 0.001 / | 0.001 / |

### Free Tier
Most API operations include a monthly free tier of 100-1000 requests per month. Free certificate tiers (digicert-free-1-free, symantec-free-1-free) are available at no cost but have limited validity periods (3-12 months).

### Usage Limits
- **API Rate Limits**: 10-100 QPS per user depending on the specific API
- **Free Certificate Limits**: Limited to specific certificate types with shorter validity periods
- **CSR Generation**: Up to 100 free requests per month

### Billing Notes
- Each API call counts as one request regardless of success or failure
- Certificate purchases are billed separately from API calls
- Free tiers reset monthly
- Paid certificates are charged at the time of order creation