v3 API Authentication

The v3 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.

App Key & App Secret

Do not include a token query parameter. Pass the App Key and signature in headers:

curl "https://singer.caiyunhub.com/v3/{endpoint}?{query}" \
  -H "x-cy-app-key: {app_key}" \
  -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 the query parameters.
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 through either the query string or the Authorization header:

Query parameter

curl "https://singer.caiyunhub.com/v3/{endpoint}?token={token}&{query}"

Header

curl "https://singer.caiyunhub.com/v3/{endpoint}?{query}" \
  -H "Authorization: Bearer {token}"