Authentication

Every request to the API v2 must be authenticated with your private key, a single secret taken from your dashboard. The examples throughout this reference use it.

The API v2 also accepts an OAuth access token.

Both are accepted on every api/v2 endpoint.

Private key

Send the private key as the username of an HTTP Basic credential, with an empty password. The trailing : in the example below is what tells curl the password is empty — without it, curl prompts for one.

$ curl --location --request GET 'https://youcanpay.com/api/v2/account/me' \
  -u 'pri_9b2efcdf-4493-4f7c-9c31-8d0a2e5f1b7a:'

That sends a standard Authorization header, so any HTTP client can do the same without curl:

Authorization: Basic cHJpXzliMmVmY2RmLTQ0OTMtNGY3Yy05YzMxLThkMGEyZTVmMWI3YTo=

Your private key carries full access to your account. Keep it server-side, never expose it in browser or mobile code, and rotate it from the dashboard if it leaks.

Sandbox keys

The API v2 accepts live private keys only. A sandbox key (pri_sandbox_...) is rejected with 401. Sandbox keys remain valid on the sandbox endpoints described in Sandbox & Testing.

OAuth access token

Send the access token as a bearer token:

$ curl --location --request GET 'https://youcanpay.com/api/v2/account/me' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN_eyJpc3...'

See Access Token for how to obtain one, and Refresh Token for renewing it.

Scopes

Scopes constrain what an OAuth access token is allowed to do. Each endpoint in this reference lists a Required scope (OAuth only), and a token missing that scope receives 403.

Scopes do not apply to private keys. A private key is a credential for your own account and reaches every endpoint regardless of the scope listed.

Errors

Status	Meaning
401	The credential is missing, malformed, not a live private key, or does not match an account.
403	Authenticated, but not permitted: an OAuth token missing the required scope, an inactive account, or an account whose identity is not verified.

A failed authentication returns:

{
  "message": "Unauthenticated."
}