API overview and authentication

Updated at:
Copy as MD

Before embedding ADA capabilities into your own systems, you need to understand API grouping, authentication methods, and invocation conventions. Open APIs are grouped by resource type. Unified authentication and error conventions reduce integration costs.

How it works

ADA Open APIs follow the Alibaba Cloud OpenAPI specification. Requests are signed with an AccessKey pair. After the signature is verified, a RAM policy is evaluated to determine whether the identity is allowed to call the target API.

Authentication only verifies that the caller has access to the API. It does not broaden the data the caller can see. API calls and console operations share the same permission model: resource ownership determines which agents and connectors you can operate on, and data permission policies determine which rows and columns are returned in queries. For more information, see Members and permissions.

APIs are grouped by resource, and names follow an action-plus-resource convention. List operations start with List, single-object reads start with Get, and write operations use Create, Update, and Delete. Examples include ListAgents, GetAgent, CreateSkill, and UpdateConnector. Once you understand this convention, you can infer most API names without looking them up one by one.

Usage notes

The available APIs are subject to the version published on the OpenAPI portal. For the overall structure, authentication, and invocation conventions, see the sections below. For the parameters and response structures of individual APIs, refer to the portal.

APIs are provided on a per-region basis. You must specify a region in each request. Resources in one region do not appear in the response of another region.

The currently available APIs are divided into four groups by resource type.

Group

Representative APIs

Scope

Agent management

ListAgents, GetAgent, CreateAgent, UpdateAgent, DeleteAgent, ListAgentVersions

Query, create, modify, delete agents, and view agent versions

Session execution

SendWebShellRequest, GetWebShellEvents

Send requests to agents and read the execution process and results as an event stream

Capabilities and resources

ListSkills, CreateSkill, RegisterMcpServer, ProbeMcpServer, UpdateConnector, ListKnowledgeBases

Manage skills, MCP servers, connectors, and knowledge bases

Data and artifacts

ListDataPermissionPolicies, PublishDataPermissionPolicy, ListArtifacts, ShareArtifact

Maintain data permission policies and query or share artifacts

Prepare credentials

The permission scope of your credentials determines the blast radius if they are leaked. Apply the principle of least privilege from the start. Do not use your Alibaba Cloud account to test the integration and then tighten permissions later.

  1. Create a RAM user dedicated to the integration in the RAM console. Do not use your Alibaba Cloud account. The permissions of an Alibaba Cloud account AccessKey pair cannot be narrowed, and a leak would compromise the entire account.

  2. Create an AccessKey pair for the RAM user and store it in the credential management facility of your integration system. Do not commit credentials to code repositories, configuration files, or logs.

  3. Configure a RAM policy that grants only the APIs actually called by this integration. Do not grant write permissions for read-only integrations.

  4. Verify that the resource ownership and data permission policies for this identity are properly configured. When authentication succeeds but the policy does not authorize access, the API returns a success response with empty data. This issue is easily misidentified as an API error.

  5. Create separate RAM users for different purposes. When multiple integrations share a single identity, you cannot distinguish the source from call records, and credential rotation affects all integrations.

Make API requests

Three invocation methods apply to different stages. Use the portal for debugging during verification, use an SDK during integration, and construct signatures directly only in special scenarios.

Debugging online in the OpenAPI portal is the fastest way to verify parameters and response structures. Debug records also provide equivalent code examples. After you confirm the API behavior, switch to the official SDK for integration. The SDK handles signature generation, retries, and error mapping. For more information, see the SDK user guide. If you need to call an API from a runtime environment not covered by the SDK, send HTTPS requests directly following the signature specification.

Requests must include the region parameter. The request ID in the response is used for troubleshooting. If your integration system logs this ID, you can trace it back to a specific call.

Handle call failures

Failures fall into three categories with different handling approaches. Identify the category before deciding whether to retry.

Signature and authentication failures indicate credential or permission issues. Retries are ineffective. Check whether the system clock has excessive drift, whether the AccessKey pair is valid, and whether the RAM policy covers the target API.

A parameter validation failure indicates that the request does not conform to the API specification, and retrying with the same request will not help. The response includes the specific fields that failed validation. Fix the issues as indicated and then call the API again.

Throttling and server-side errors are retriable. Use exponential backoff for retries to avoid aggressive fixed-interval retries that can worsen throttling. Before retrying a write operation, verify whether the API is idempotent. Retrying a non-idempotent API may create duplicate resources.

Apply to production environments

Rotate credentials periodically and support hot swapping. During rotation, keep both the old and new AccessKey pairs active. Disable the old credentials only after the switchover is complete to avoid call interruptions.

Include API calls in your monitoring. API call counts are tracked in usage statistics, and abnormal traffic can quickly exhaust your quota. For more information, see Usage and quotas.

Implement your own confirmation mechanism for integrations that involve write operations. Manual confirmations on the ADA side occur within sessions. Tasks initiated automatically by external systems have no one to respond to confirmation requests. Therefore, perform reviews on the external system side before calling high-impact operations. For more information, see Approval and manual confirmation.

FAQ

  • Q: The API returns a success response but the data is empty?

    A: First, verify that the region parameter matches the region where the resource resides. Then, confirm that the calling identity's resource ownership and data permission policies cover the target resource. Passing authentication does not mean the identity is authorized to access the corresponding data.

  • Q: Can I use the Alibaba Cloud account AccessKey to make API calls?

    A: It is technically possible but not recommended. The permissions of an Alibaba Cloud account's credentials cannot be narrowed down. If the credentials are leaked, the entire account is at risk, and you cannot distinguish call records by integration source. Use RAM user credentials and follow the principle of least privilege.

  • Q: Where can I find API definitions?

    A: Refer to the versions published on the OpenAPI portal. The portal provides parameter descriptions, response structures, online debugging, and code samples in various languages. This document only describes the overall structure and calling conventions.

  • Q: Signature verification keeps failing?

    A: First, check whether the local system time deviates from the standard time, as signature verification is time-sensitive. Then, verify that the parameter encoding and sorting comply with the signature specification. Constructing signatures manually is error-prone. Switching to the official SDK can help you avoid such issues.