v1 API Authentication

The v1 API supports App Key & App Secret authentication and legacy token authentication. App Key & App Secret is recommended because requests are signed without exposing the secret.

WARNING

v1 credentials are passed in the URL query string. This differs from v2.6 and v3.

App Key & App Secret

Pass the App Key as the token query parameter and include the signature headers:

curl "https://api.caiyunapp.com/v1/{endpoint}?token={app_key}&{query}" \
  -H "x-cy-nonce: {nonce}" \
  -H "x-cy-timestamp: {timestamp}" \
  -H "x-cy-signature: {signature}"

To calculate x-cy-signature:

1. Sort and URL-encode all query parameters, including token.
2. Join the values as {method}:{path}:{query}:{app_key}:{nonce}:{timestamp}.
3. Calculate HMAC-SHA256 with the App Secret.
4. Encode the result with URL-safe Base64.

Use a unique 16–40 character nonce for every request. The timestamp is Unix time in seconds.

Token Authentication

WARNING

Token authentication can expose credentials through URLs and logs. Prefer App Key & App Secret.

Pass the API authentication credential in the token query parameter:

curl "https://api.caiyunapp.com/v1/{endpoint}?token={token}&{query}"