# cas-instance

Part of **CAS**

# Certificate Management Service Instance Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Manage Instances | Synchronous | Perform operations on certificate service instances including listing, describing, and updating configurations. |
| Manage Cloud Access | Synchronous | Add and delete cloud access keys for certificate service integration. |
| Refund Instance | Synchronous | Process refunds for certificate service instances. |

## API Calling Patterns

### Authentication
The primary authentication method is **Bearer Token**.

- Include the header: `Authorization: Bearer <your_api_key>`
- Store your API key in the environment variable: `DASHSCOPE_API_KEY`
- While other auth methods may exist (e.g., Alibaba Cloud AccessKey), Bearer Token is used consistently across all documented examples and is recommended for simplicity.

### Service Endpoint
APIs use multiple base URLs depending on region and function:

- China region: `https://cas.aliyuncs.com` or `https://api.aliyun.com/api/cas/2020-04-07`
- International region: `https://cas.alibabacloud.com` or `https://api.alibabacloud.com/api/cas/2020-04-07`

Common regions include `cn-hangzhou`, `cn-shanghai`, and `ap-southeast-1`, but most endpoints are global (`region: all`) and do not require region-specific routing.

### Synchronous API Pattern
All operations in this domain are **synchronous**:
1. Send an HTTP request (GET or POST) to the appropriate endpoint
2. Include required parameters in query string (GET) or JSON body (POST)
3. Receive a complete JSON response immediately
4. Parse the `RequestId` and operation-specific fields from the response

No polling or streaming is required. Errors are returned directly in the response with standard HTTP status codes.

## Parameter Reference

### Manage Instances

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| InstanceId | string | Yes | — | — | The ID of the Certificate Management Service instance. |
| Keyword | string | No | — | — | A fuzzy query that matches a domain name, instance name, or resource ID. |
| Status | string | No | — | one of: inactive, pending, willExpire, expired, refund, normal, closed | The instance status. Used to filter instances. |
| Brand | string | No | — | one of: WoSign, CFCA, DigiCert, GeoTrust, GlobalSign, vTrus, Alibaba | The certificate authority (CA) brand. |
| CertificateType | string | No | — | one of: DV, OV, EV | The type of the certificate. |
| CertificateStatus | string | No | — | one of: issued, revoked, willExpire, expired | The status of the certificate. |
| InstanceType | string | No | — | one of: BUY, TEST | The instance type. BUY indicates a paid certificate. TEST indicates a test certificate. |
| ResourceGroupId | string | No | — | — | The ID of the resource group. |
| ShowSize | integer | No | 10 | range 1-100 | The number of entries to return on each page. |
| CurrentPage | integer | No | 1 | range 1-999999 | The page number. |

### UpdateInstance

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| InstanceId | string | Yes | — | — | The ID of the instance. |
| CertificateName | string | No | — | — | The name of the instance. |
| Domain | string | No | — | Supports single domains and wildcards (e.g., *.aliyundoc.com); multiple domains separated by comma | The domain name to bind to the certificate. |
| KeyAlgorithm | string | No | RSA_2048 | One of: RSA_2048, RSA_3072, RSA_4096, ECC_256, SM2 | The key algorithm for the certificate. |
| AutoReissue | string | No | — | One of: enable, disable | Specifies whether to enable automatic management. |
| CompanyId | integer | No | — | — | The ID of the company information. Required for OV and EV certificates. |
| ContactIdList | array | No | — | Array of integers; at least one element required | The contact IDs. |
| GenerateCsrMethod | string | No | online | One of: online, upload | The CSR generation method. |
| Csr | string | No | — | Must be a valid CSR string in PEM format | The CSR content. |
| ValidationMethod | string | No | — | One of: DNS, HTTP | The domain ownership validation method. |
| City | string | No | Beijing | — | The city where the certificate requester's company is located. |
| Province | string | No | Beijing | — | The province or region where the company is located. |
| CountryCode | string | No | CN | — | The country or region code (e.g., CN, US). |
| ResourceGroupId | string | No | — | — | The ID of the resource group. |
| Tags | array<object> | No | — | Up to 20 tags; TagKey max 64 chars, no aliyun/acs: prefix; TagValue max 128 chars | The tags to attach to the instance. |

### Manage Cloud Access

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| SecretId | string | No | — | — | The AccessKey ID that is used to access cloud resources. |
| CloudName | string | No | — | Must be 'Tencent' | The cloud service provider (currently only Tencent supported in examples). |
| CurrentPage | integer | No | 1 | — | The page number. |
| ShowSize | integer | No | — | One of: 10, 20, 50 | The number of entries per page. |
| SecretKey | string | No | — | — | The secret corresponding to the AccessKey. |

### Refund Instance

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| InstanceId | string | Yes | — | — | The ID of the instance to refund (must be within 7 days of purchase). |

## Code Examples

### List Certificate Instances - Python - All Regions

```python
import requests
import json

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

# Define the request parameters
params = {
    "Keyword": "test",
    "Status": "inactive",
    "ShowSize": 10,
    "CurrentPage": 1
}

# 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}")
```

### Get Instance Details - curl - All Regions

```bash
curl -X GET \
  'https://cas.api.alibabacloud.com/2020-04-07/GetInstanceDetail?InstanceId=cas_dv-cn-123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'
```

### Delete Instance - Python - All Regions

```python
import requests

url = "https://cas.aliyuncs.com/api/v1/instances/delete"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "InstanceId": "cas-cn-68n1mm16****"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

### Update Instance Configuration - Python - All Regions

```python
import requests
import json

# Set up the API endpoint
url = "https://cas.aliyuncs.com/api/v1/instances/update"

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

# Set up the request body
payload = {
    "InstanceId": "cas-cn-68n1mm16****",
    "CertificateName": "example-cert",
    "Domain": "test.com",
    "KeyAlgorithm": "RSA_2048",
    "AutoReissue": "enable",
    "CompanyId": 44211,
    "ContactIdList": [123],
    "GenerateCsrMethod": "online",
    "ValidationMethod": "DNS",
    "City": "Beijing",
    "Province": "Beijing",
    "CountryCode": "CN",
    "ResourceGroupId": "rg-ae****4wia",
    "Tags": [
        {
            "TagKey": "Environment",
            "TagValue": "Production"
        }
    ]
}

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

# Print the response
print(response.json())
```

### Delete Instance - curl - All Regions

```bash
curl -X POST https://cas.aliyuncs.com/api/v1/instances/delete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"InstanceId": "cas-cn-68n1mm16****"}'
```

## Response Format

```json
{
  "RequestId": "4BD0CBD9-FB03-5ECD-A8FD-F90C62D78095"
}
```

**Key Fields**:
- `RequestId` — Unique identifier for the API request; useful for troubleshooting and support
- For `ListInstances` and `GetInstanceSummary`: `TotalCount`, `ShowSize`, `CurrentPage` provide pagination context
- For `GetInstanceDetail`: `InstanceId`, `Status`, `Domain`, `CertificateStatus`, `CertificateNotAfter`, `AutoReissue` are critical for monitoring and automation

## Error Handling

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|-------------------|----------------------------|----------------------------------------|
| 400 | Invalid parameter provided. Check the request parameters and ensure InstanceId is valid. | Validate all input parameters against constraints (e.g., enum values, formats). |
| 403 | Access denied. The user does not have sufficient permissions to perform this operation. | Ensure your API key has the required RAM permissions for CAS actions. |
| 404 | Instance not found. The specified InstanceId does not exist or has already been deleted. | Verify the InstanceId exists using `ListInstances` or `GetInstanceDetail`. |
| 429 | Too many requests. Rate limiting has been triggered. Wait before retrying. | Implement exponential backoff; reduce request frequency below 100 QPS. |
| 500 | Internal server error. Retry the request after a short delay. If the issue persists, contact technical support. | Retry with jittered backoff; if persistent, report RequestId to Alibaba Cloud support. |
| InvalidParameter.CloudName | The specified CloudName parameter is invalid. Ensure it is set to 'Tencent'. | Only use supported cloud provider names as documented. |
| Throttling | The request exceeds the rate limit of 100 queries per second (QPS) per user. | Space out requests; implement client-side rate limiting. |

### Rate Limits & Retry
- **100 QPS per account/user** across all Instance Management APIs
- Requests exceeding this limit receive `429` or `Throttling` errors
- Recommended retry strategy: exponential backoff starting at 100ms, max 5 retries
- Do not retry `400` or `404` errors—fix the request instead

## Environment Requirements

- Set your API key: `export DASHSCOPE_API_KEY=your_api_key_here`
- Required Python packages (for examples): `requests`
- Install via: `pip install requests`
- Compatible with Python 3.6+ and standard HTTP clients (curl, Postman, etc.)

## FAQ

Q: How do I authenticate API requests?
A: Use a Bearer Token in the `Authorization` header: `Authorization: Bearer YOUR_API_KEY`. Store your key in the `DASHSCOPE_API_KEY` environment variable.

Q: Can I refund a certificate instance after 7 days?
A: No. The `RefundInstance` API only works within 7 days of purchase. After that, refunds are not supported.

Q: Why am I getting a 404 error when querying an instance?
A: The `InstanceId` may be incorrect, already deleted, or belong to a different Alibaba Cloud account. Verify using `ListInstances`.

Q: Are there free calls available?
A: Yes. Most APIs offer 100–1000 free calls per month. Check the pricing section for details per operation.

Q: What cloud providers are supported for `AddCloudAccess`?
A: Documentation examples show support for (`CloudName: Tencent`). Other providers like AWS, Azure, and HUAWEI CLOUD are mentioned in parameter descriptions but require exact credential formatting per provider.

## Pricing & Billing

### Billing Model
All APIs use **per-request billing**. Each successful or failed API call counts as one request.

### Price Reference

| Tier/Model | Input Price | Output Price |
|------------|-------------|--------------|
| standard | 0.001 / | 0.001 / |

### Free Tier
- `ListInstances`, `GetInstanceDetail`, `GetInstanceSummary`, `ListCloudAccess`: 1000 free calls/month
- `DeleteInstance`, `UpdateInstance`, `RefundInstance`, `AddCloudAccess`, `DeleteCloudAccess`: 100 free calls/month

### Usage Limits
- 100 QPS per account/user across all Instance Management APIs
- `ListInstances`: Maximum 100 records per request (`ShowSize` ≤ 100)

### Billing Notes
- Free tier resets monthly
- Charges apply per call, regardless of response success
- `RefundInstance` does not refund the original certificate purchase—only waives the API call fee if within free tier