Skip to main content

​
What it is

YCloud uses API keys to identify your account and authorize API requests. Send the key only from trusted server-side code.

​
Before you begin

Create or retrieve an API key in your YCloud account. Decide where each environment will store its secret before you add the key to application code.

​
Request

Send the key in the X-API-Key header on every request.
Do not add a Bearer prefix. The header value is the API key itself.

​
Response

Valid credentials allow the endpoint to return its normal success response. Invalid or unauthorized credentials return a 4xx error response.

​
Store keys securely

  • Keep API keys in a secret manager or an encrypted environment variable.
  • Use API keys only in trusted server-side code.
  • Never place a key in a URL, browser bundle, mobile application, log, or screenshot.
  • Use separate keys for separate environments when your account setup allows it.
  • Rotate a key immediately if you believe it has been exposed.
For local development, export the key in your shell:
Read it from the environment in your application. Do not hard-code it.

​
Rotate a key

Create or select the replacement key, deploy it to every service that calls YCloud, verify traffic with the new key, and then revoke the old key. If you suspect exposure, rotate first and investigate afterward.

​
Troubleshoot authentication

An authentication failure returns a 4xx response. Check that:
  • The request uses https://api.ycloud.com/v2.
  • The header name is exactly X-API-Key.
  • The key does not contain extra spaces or quotation marks.
  • The key is active and belongs to the intended YCloud account.
  • The account can access the product used by the endpoint.
Log the response requestId for troubleshooting, but never log the API key. See Errors for the response format.

Test authentication

Verify a key with a read-only Balance API request.