# pai-workspace

Part of **PAI**

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

> 💡 **Path Selection**: This skill is one implementation path for [Manage platform access and permissions](../../intent/pai-manage-permissions/SKILL.md). If you're unsure which path to take, check the routing skill first.

# Platform for AI (PAI) Workspace & Identity Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Get Workspace ID and Name | Synchronous | Retrieve workspace identification information. |
| Create Workspace Specification Template | Synchronous | Define templates for workspace specifications. |
| Submit Workload Specification | Synchronous | Submit specifications for workloads using workspace templates. |
| Get Workspace Role Info | Synchronous | Retrieve information about a specific workspace role. |
| List Workspace Entities | Synchronous | List workspace users, roles, permissions, and members. |
| Get Workspace Entities | Synchronous | Retrieve details of specific workspace members and permissions. |
| Update Workspace | Synchronous | Update workspace configuration and settings. |
| Get User Information | Synchronous | Retrieve details about the current user in PAI. |
| Manage User Configurations | Synchronous | List, set, and delete user-specific configurations. |
| Query User Configuration | Synchronous | Retrieve user-specific configuration settings. |
| Access Identity Verification API | Synchronous | Access the list of identity verification API operations. |
| Manage PAILLMTrace Permissions | Synchronous | Configure RAM authorization for PAILLMTrace service. |
| Configure Credential Injection | Synchronous | Set up credential injection for secure access to resources. |

## API Calling Mode

### Authentication
The primary authentication method is **Bearer Token** via the `Authorization` header.

- Use the header: `Authorization: Bearer <your_api_key>`
- Store your API key in the environment variable: `DASHSCOPE_API_KEY`
- While some endpoints may support other methods (e.g., AccessKey), Bearer Token is recommended for consistency across all PAI Workspace APIs.

### Service Endpoint
APIs use region-specific endpoints with the following pattern:

```text
https://api.aliyun.com/api/AIWorkSpace/2021-02-04/{Operation}
```

For international regions, use:
```text
https://api.alibabacloud.com/api/AIWorkSpace/2021-02-04/{Operation}
```

Common regions include:
- `cn-hangzhou`
- `cn-shanghai`
- `cn-beijing`

Note: Some user and configuration APIs use different base paths (e.g., `/api/PaiPlugin/2022-01-12/GetUser` or `/api/pai-dsw/2022-01-01/GetUserConfig`), but all follow the same authentication and regional patterns.

### Synchronous API Pattern
All operations in this domain are **synchronous**:
1. Send an HTTP request (GET, PUT, POST, or DELETE) to the appropriate endpoint
2. Include required parameters as query strings (for GET/DELETE) or in the JSON body (for PUT/POST)
3. Include the `Authorization: Bearer <your_api_key>` header
4. Receive a complete JSON response immediately
5. Parse the response for success data or error codes

No polling or streaming is required—each call returns final results in a single response.

## Parameter Reference

### Get Workspace Role Info

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | true | — | — | The workspace ID. You can obtain this ID by calling the ListWorkspaces operation. |
| RoleId | string | false | — | — | The custom role ID. |

### List Workspace Entities

#### ListWorkspaceUsers
| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | false | — | — | The workspace ID. For more information, see ListWorkspaces. |
| UserName | string | false | — | — | The display name of the user that can be added as a workspace member. |
| UserId | string | false | — | — | — |

#### ListWorkspaceRoles
| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | true | — | — | The workspace ID. Call the ListWorkspaces operation to get it. |
| PageNumber | integer | false | 1 | range 1 to infinity | The page number. Pages start from 1. |
| PageSize | integer | false | 20 | range 1 to 100 | The number of entries per page. |
| RoleIds | string | false | — | — | A comma-separated list of role IDs. |
| RoleName | string | false | — | — | The role name. |
| RoleType | string | false | — | one of: custom | The role type. |
| VerboseFields | string | false | — | one of: ModulePermissions | Fields to return; only ModulePermissions supported. |
| SortBy | string | false | GmtCreateTime | one of: GmtCreateTime, GmtModifiedTime | Sort field. |
| Order | string | false | ASC | one of: ASC, DESC | Sort order. |
| Status | string | false | — | one of: Creating, Updating, Deleting, Succeeded, Failed | The status. |

#### ListMembers
| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | true | — | — | Workspace ID. |
| PageNumber | integer | false | 1 | range 1 to max | Page number. |
| PageSize | integer | false | 20 | max 100 | Number of entries per page. |
| Roles | string | false | — | one of: PAI.AlgoDeveloper, PAI.AlgoOperator, PAI.LabelManager, PAI.MaxComputeDeveloper, PAI.WorkspaceAdmin, PAI.WorkspaceGuest, PAI.WorkspaceOwner | Roles to filter members. |
| MemberName | string | false | — | max length 255 chars | Username (fuzzy match). |

### Get Workspace Entities

#### GetMember
| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | true | — | — | The workspace ID. |
| UserId | string | false | — | — | The user UID. Specify either UserId or MemberId. |
| MemberId | string | false | — | — | The member UID. Specify either UserId or MemberId. |

#### GetPermission
| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | true | — | — | The workspace ID. |
| PermissionCode | string | true | — | — | The name of the permission. |
| Accessibility | string | false | — | one of: PUBLIC, PRIVATE | Access type. |
| Creator | string | false | — | — | UID of the creator. |
| Resource | string | false | — | — | The resource. |
| Option | string | false | — | one of: ResourceEmpty, DisableRam | Optional configurations. |
| Labels | object | false | — | — | — |

### Update Workspace

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| WorkspaceId | string | true | — | — | The ID of the workspace. |
| DisplayName | string | false | — | 3-23 characters, starts with letter, contains only letters, digits, and underscores, unique per region | Display name of the workspace. |
| Description | string | false | — | — | Description of the workspace. |

### Manage User Configurations

#### SetUserConfigs
| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| ConfigKey | string | true | — | — | The configuration key. |
| ConfigValue | string | true | — | — | The configuration value. |
| CategoryName | string | true | — | Only 'DataPrivacyConfig' is supported | The classification. |
| Scope | string | true | — | One of: subUser, owner | The scope. |

#### DeleteUserConfig
| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| CategoryName | string | true | — | — | The classification. Only DataPrivacyConfig supported. |
| ConfigKey | string | false | — | — | The configuration key. Only customizePAIAssumedRole supported. |
| Scope | string | false | — | one of: subUser, owner | The scope. |

### Manage PAILLMTrace Permissions

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Effect | string | true | — | one of: Allow, Deny | Authorization effect. |
| Action | string | true | — | — | One or more API operations. |
| Resource | string | false | — | — | Alibaba Cloud Resource Name (ARN). |
| Condition | object | false | — | — | Conditions for policy activation. |

### Configure Credential Injection

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| Enable | boolean | false | — | — | Specifies whether to enable credential injection. |
| AliyunEnvRoleKey | string | false | — | — | The key of the environment variable role. |
| Configs | array | false | — | — | The list of configurations. |

## Code Examples

### Get Workspace Role Info - Python - All Regions

```python
import requests

url = "https://api.aliyun.com/api/AIWorkSpace/2021-02-04/GetWorkspaceRole"
params = {
    "WorkspaceId": "image-tzi7f9czc0cxs9s45t",
    "RoleId": "role-sw******2tij"
}
headers = {
    "Authorization": "Bearer <your-api-key>",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())
```

### List Workspace Users - Bash - All Regions

```bash
curl -X GET 'https://api.aliyun.com/api/AIWorkSpace/2021-02-04/ListWorkspaceUsers?WorkspaceId=12345&UserName=doctest****' \
-H 'Authorization: Bearer $DASHSCOPE_API_KEY'
```

### List Permissions - Python - All Regions

```python
import requests

url = "https://api.aliyun.com/api/AIWorkSpace/2021-02-04/ListPermissions"
params = {
    "WorkspaceId": "123"
}
headers = {
    "Authorization": "Bearer $DASHSCOPE_API_KEY",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())
```

### Update Workspace - Bash - All Regions

```bash
curl -X PUT https://api.aliyun.com/api/AIWorkSpace/2021-02-04/UpdateWorkspace/123 \
-H "Authorization: Bearer <your-api-key>" \
-H "Content-Type: application/json" \
-d '{
  "DisplayName": "workspace-example",
  "Description": "This is an example workspace."
}'
```

### Get Member Details - Bash - All Regions

```bash
curl -X GET 'https://api.aliyun.com/api/AIWorkSpace/2021-02-04/GetMember?WorkspaceId=145883&UserId=21513926******88039' \
-H 'Authorization: Bearer <your-api-key>' \
-H 'Content-Type: application/json'
```

### List Members with Pagination - Bash - All Regions

```bash
curl -X GET 'https://api.aliyun.com/api/AIWorkSpace/2021-02-04/ListMembers?WorkspaceId=123&PageNumber=1&PageSize=20' \
-H 'Authorization: Bearer $DASHSCOPE_API_KEY'
```

### Delete User Configuration - Bash - All Regions

```bash
curl -X DELETE https://api.aliyun.com/api/AIWorkSpace/2021-02-04/DeleteUserConfig?CategoryName=DataPrivacyConfig&ConfigKey=tempStoragePath&Scope=subUser \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json"
```

### List Workspace Roles - Bash - All Regions

```bash
curl -X GET 'https://api.aliyun.com/api/AIWorkSpace/2021-02-04/ListWorkspaceRoles?WorkspaceId=87***&PageNumber=1&PageSize=20' \
-H 'Authorization: Bearer $DASHSCOPE_API_KEY' \
-H 'Content-Type: application/json'
```

## Response Format

```json
{
  "RequestId": "A519F77D-28A0-52F5-AB82-5********8",
  "RoleName": "dev-test",
  "RoleId": "role-dhg*******\n",
  "GmtCreateTime": "2025-06-11T08:58:35.438Z",
  "GmtModifiedTime": "2026-03-27T02:26:33.872Z",
  "Creator": "2680******4103",
  "ModulePermissions": [
    {
      "ModuleName": "PaiDesigner",
      "PermissionType": "ReadOnly",
      "Permissions": [
        {
          "PermissionCodes": [
            "PaiDLC:GetTensorboard"
          ],
          "PermissionRules": [
            {
              "Accessibility": "PRIVATE",
              "EntityAccessType": "CREATOR"
            }
          ]
        }
      ]
    }
  ],
  "Status": "Successful"
}
```

**Key Fields**:
- `RequestId` — Unique identifier for the API request
- `RoleName` — Human-readable name of the role
- `RoleId` — Unique identifier for the role
- `GmtCreateTime` — UTC timestamp when the role was created
- `GmtModifiedTime` — UTC timestamp when the role was last modified
- `Creator` — User ID of the role creator
- `ModulePermissions` — Detailed permissions grouped by PAI module
- `Status` — Current operational status of the role

## Error Handling

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|-------------------|----------------------------|----------------------------------------|
| 400 | Bad Request. The request parameters are invalid or malformed. | Validate all parameters against API constraints and retry. |
| 401 | Unauthorized. The API key or credentials are missing or invalid. | Ensure `DASHSCOPE_API_KEY` is set correctly and has required permissions. |
| 403 | Forbidden. The caller does not have sufficient permissions to access the specified workspace or role. | Check RAM policies and ensure your account has necessary workspace permissions. |
| 404 | Not Found. The specified workspace or role ID does not exist. | Verify the `WorkspaceId` and `RoleId` using `ListWorkspaces` or `ListWorkspaceRoles`. |
| 500 | Internal Server Error. An unexpected error occurred on the server side. | Retry the request after a short delay; contact support if persistent. |
| 503 | Service Unavailable. The service is temporarily unavailable due to overload or maintenance. | Implement exponential backoff and retry logic. |
| InvalidParameter.WorkspaceId | The specified WorkspaceId is invalid or does not exist. | Confirm workspace ID format and existence via `ListWorkspaces`. |
| UnauthorizedOperation | The caller does not have sufficient permissions to list permissions in the specified workspace. | Assign appropriate RAM role with `paiworkspace:ListPermissions` permission. |
| Throttling | The request rate exceeds the allowed limit. Wait and retry after a short delay. | Reduce request frequency or implement rate limiting in your client. |
| 429 | Too Many Requests. The request rate exceeds the allowed limit. | Apply backoff strategy; consider batching requests where possible. |

### Rate Limits & Retry
- Standard QPS limit: **100 requests per second** per account/user
- Free tier: **1,000 free calls per month** (resets monthly)
- Recommended retry strategy: Exponential backoff with jitter (e.g., 1s, 2s, 4s, 8s delays)
- On `429` or `Throttling` errors, respect any `Retry-After` header if present

## Environment Requirements

- Set your API key: `export DASHSCOPE_API_KEY=your_api_key_here`
- Required SDKs (if using official clients):
  - Python: `requests` (no special PAI SDK required for REST APIs)
  - Java: Use standard HTTP clients like OkHttp or Apache HttpClient
- No specific runtime version requirements beyond standard HTTP client compatibility

## FAQ

Q: How do I obtain a WorkspaceId?
A: Call the `ListWorkspaces` API (not detailed in this skill) or find it in the PAI Console under Workspace settings. Most workspace-related APIs require this ID as a path or query parameter.

Q: What permissions do I need to manage workspace roles and members?
A: Your account must have RAM policies granting `paiworkspace:GetWorkspaceRole`, `paiworkspace:ListWorkspaceRoles`, `paiworkspace:ListMembers`, and similar actions. Workspace owners have full access by default.

Q: Can I use the same API key across different regions?
A: Yes, the `DASHSCOPE_API_KEY` works globally. However, you must use the correct regional endpoint (`api.aliyun.com` for China, `api.alibabacloud.com` for international).

Q: Why am I getting a 403 error when listing workspace entities?
A: This usually means your account lacks the necessary RAM permissions for the target workspace. Contact your workspace administrator to grant you appropriate roles like `PAI.WorkspaceAdmin` or custom roles with required permissions.

Q: Are there any free operations in the Workspace API?
A: Most operations include a free tier of 1,000 calls per month. After that, they are billed per request. Check the Pricing & Billing section for exact rates.

## Pricing & Billing

### Billing Model
All operations are billed **per request**, regardless of response size or complexity. Each successful or failed API call counts as one request.

### Price Reference

| Tier/Model | Input Price | Output Price |
|------------|-------------|--------------|
| default | 0.001 / | 0.002 / |
| standard | 0.0001 / | 0.0001 / |

(Note: Different functions have slightly different pricing tiers as extracted from documentation.)

### Free Tier
Monthly free allowance of **1,000 API calls** for most operations. The free tier resets at the beginning of each calendar month.

### Usage Limits
- **Rate limit**: 100 QPS per account/user
- **Pagination limits**: Up to 100 records per page for lists
- **String constraints**: e.g., DisplayName must be 3–23 characters

### Billing Notes
- Each API call is billed as one request, even if it returns an error
- Free tier applies across all Workspace & Identity Management APIs collectively
- Billing occurs based on actual usage beyond the free tier; no upfront costs