The four credential classes
A credential can never widen. A client session cannot exceed the credential that issued it or the products the app has enabled, and a restricted key cannot reach a capability the app is not entitled to.
The standard server key
Partner-authenticated endpoints use HTTP Basic auth.- Username: your app ID
- Password: your app secret
- Header:
Authorization: Basic base64(<APP_ID>:<APP_SECRET>)
200 from GET /v2/partners/config confirms the key is valid for the environment behind that host. The response also reports credentialType (standard or restricted) and credentialMode, which should read app_secret for anything your backend does. What else the response contains, and how to branch on it, is on Get configuration.
The date-based version contract
The/v2 path identifies the product major. Each app environment is also pinned to an immutable date-based contract such as 2026-09-09. Read apiVersion from GET /v2/partners/config and record it with your deployment; supportedApiVersions lists what the deployment still accepts on new requests.
You may omit Stableyard-Version, in which case Stableyard uses the environment pin. To assert a version explicitly, send the exact value you read:
Stableyard-Version, including error responses. Any Stableyard-Version other than your environment’s pinned version is rejected, even one Stableyard supports. Client session tokens, payment client secrets, Payments and webhook events all stay bound to the version under which they were created, so a version change does not rewrite resources that already exist.
Browser and mobile: client sessions
Client API routes under/v2/client/* use short-lived bearer tokens.
1
Your backend creates the session
POST /v2/client-sessions with the standard server key, granting only the permissions that one client flow needs.2
Your backend hands over the session token
The response carries an opaque
clientSessionToken. That is what reaches the browser or mobile app, never the app secret.3
The client exchanges it
POST /v2/client/auth/exchange returns an accessToken.4
The client calls with the access token
Authorization: Bearer <accessToken> on subsequent /v2/client/* calls. The exchange response returns the effective permission list, so the client can hide unavailable actions rather than guess.account:read when permissions is omitted, and it cannot exceed the issuing credential’s permissions or the app’s enabled products.
Both
accountId and externalUserId are strict lookups here. The account must already exist: creating a client session never creates or updates one. Call POST /v2/accounts from your backend first, with an explicit subjectType.
Account-bound Vault checkout needs two credentials at once. Send the client access token in Authorization: Bearer <accessToken> to identify the payer’s account, and the receive Payment’s secret in X-Stableyard-Payment-Secret to bind the request to exactly one Payment. Neither is sufficient alone. A payment client secret on its own can use only the public direct, routing and entitled hosted on-ramp methods; it can never authorize Vault spending.
An expired but correctly signed client token returns 401 with error.code: "client_token_expired", and the client should ask your backend for a new session. Malformed, forged, replayed or already-consumed tokens return 401 unauthorized and must not be retried. Do not treat the two as the same signal.
Public checkout: the payment capability token
Endpoints under/v2/public/payments/{paymentId}/* take neither an app secret nor a client token. They take the Payment clientSecret in Authorization: Bearer <clientSecret>. The payment ID is an identifier, not a credential.
Call these directly from payer-facing code. Do not attach Partner Basic auth, and keep the client secret out of URLs, analytics payloads, third-party logs, referrers and screenshots. Treat the hosted link itself as an opaque capability for one payment: it is deliberately resolvable more than once until the payment expires, so refresh, resume and multi-device payer flows work. Cancel the payment to stop accepting new payer actions when a link is disclosed unexpectedly.
Public app settings: standalone wallet funding
POST /v2/public/apps/{appId}/payments accepts no app secret. The app ID selects environment-scoped server settings; it does not authenticate the caller. The Origin check is a browser policy control, not cryptographic caller authentication, and a non-browser caller can supply that header. Treat this as a deliberate anonymous receive surface.
Stableyard requires an exact allowed Origin, an Idempotency-Key, an allowed destination and amount, and an active Payments entitlement. A successful response returns a canonical payment ID plus the scoped client secret used for the rest of checkout.
This route can only create a receive Payment for a policy-approved wallet. It cannot choose fees, webhooks, the environment, an account, or methods outside the policy. Allowed origins, destinations, amounts and methods are configured in the Partner Dashboard, under Configuration → Public Payments. Use partner-authenticated creation when the caller itself must be authenticated.
Permissions are not entitlements
A permission answers a narrow question: what may this particular key call? It never answers whether the app may offer the capability at all, and it never proves the capability is operational. Those are separate conditions. See Capabilities. The API field is namedscopes. Everywhere else, including the Partner Dashboard, they are called permissions.
Restricted keys
Use a restricted key for a narrowly scoped backend service, a reporting process or a session issuer. Do not make raw permission selection part of the normal integration path: start with a standard server key and narrow later where a service has a real least-privilege requirement.
Webhook endpoints are managed in the Partner Dashboard.
A restricted key keeps the permissions it was issued with. Enabling a module for the app later does not widen an existing key, so plan on issuing a new one. A standard key tracks the app’s enabled products instead.
Capabilities
What must be enabled before a capability works for your app.
Errors
The error envelope and the named codes.
Idempotency
Which operations require an
Idempotency-Key, and what reusing one does.