Authentication
Stableyard uses two authentication methods:
- Public Key (
sy_pub_*) — for creating and managing payments
- Wallet Auth (
sy_auth_*) — for managing your account settings
Public Key
Every account gets a public key on creation:
| Key | Prefix | Where to use |
|---|
| Public Key | sy_pub_* | Frontend, widget, your app |
| Test Public | sy_test_pub_* | Sandbox mode |
curl -X POST https://api.stableyard.fi/v2/sessions \
-H "Authorization: Bearer sy_pub_your_key_here" \
-H "Content-Type: application/json" \
-d '{ "amount": 10000000, "destination": "shop@stableyard" }'
What Public Keys Can Do
- Create payment sessions
- Preview and commit quotes (get deposit addresses)
- Read session status
- Submit transaction hashes
What Public Keys Cannot Do
- Cancel or refund sessions
- Manage webhooks
- Create deposit addresses
- Change account settings
Public keys are safe to embed in frontend code. They can only create and read payments — they cannot move money out of your account or change your settings.
Wallet Auth
For account management via dashboard or app. Users sign a challenge message with their wallet to prove ownership.
1. POST /v2/auth/challenge { wallet, chainType }
→ Returns challenge message + nonce
2. User signs the challenge in their wallet
3. POST /v2/auth/verify { wallet, chainType, signature, nonce }
→ Returns sy_auth_* token + accountId
4. Use the token for account operations
What Wallet Auth Can Do (sy_auth_*)
- View own sessions and transaction history
- Manage account settings (username, settlement preferences)
- View and regenerate API keys
- Deploy and activate vault
What Wallet Auth Cannot Do
- See other accounts’ data
- Create sessions (use public key for that)
No Auth Required
Some endpoints work without any authentication:
GET /sessions/:id — read payment status (for checkout pages)GET /network/chains — supported chainsGET /network/portfolio — wallet balances
The session ID (ses_xxx) is unguessable and acts as the access token for checkout pages.
Sandbox Mode
Use test keys (sy_test_pub_*) for development. Test sessions are auto-settled — no real blockchain transactions.
Switch to live keys when you’re ready to accept real payments.
Rate Limits
| Tier | Limit | Endpoints |
|---|
| Auth | 20 req/min | /auth/* |
| Financial | 50 req/min | Session create/pay/refund |
| General | 200 req/min | Account, webhook, other |
| Public | 100 req/min | Network status, chains, portfolio |
