Authentication & Permissions
Set up secure authentication for API access, including keys, MPC signers, and permission management.
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.example.com/v1/balances
{
"balances": [
{"asset": "ETH", "amount": "1.5", "chain": "ethereum"}
]
}
Overview
Secure all API interactions with V3 Custody using API keys, bearer tokens, or MPC threshold signers. You generate credentials through the dashboard at https://dashboard.example.com, then include them in requests. This ensures only authorized access to custody operations like signing transactions or querying balances.
MPC threshold signers provide keyless security for high-value operations, distributing signing across multiple parties. Role-based access control (RBAC) lets you assign granular permissions, such as read-only ledger access or full signing approval.
Store credentials securely. Never hardcode them in source code or commit to version control. Use environment variables or secret managers.
Authentication Methods
Choose the method that fits your use case. API keys work for simple integrations, while MPC signers suit production custody workflows.
Generate an API key from the dashboard. Use it in the Authorization header as a bearer token.
Bearer token format: Bearer YOUR_API_KEY.
const response = await fetch('https://api.example.com/v1/balances', {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
Configure MPC signers for threshold cryptography. Requires at least 3-of-5 signers for production security.
Set up signers via the Policy Engine, then request signatures through the API.
Comma-separated signer IDs, e.g., signer1,signer2,signer3.
Short-lived tokens from OAuth flows or key exchanges. Refresh automatically before expiry.
curl -H "Authorization: Bearer YOUR_TOKEN" \
https://api.example.com/v1/transactions
Generate and Configure Credentials
Follow these steps to create and set up authentication.
Create API Key
Log in to https://dashboard.example.com/keys. Click New API Key, select scopes (e.g., balances:read, transactions:sign), and copy the generated key.
Configure MPC Signers
In the dashboard, navigate to MPC Signers. Add signers with public keys and set threshold (e.g., 2-of-3).
{
"signers": [
{"id": "signer1", "publicKey": "0xabc..."},
{"id": "signer2", "publicKey": "0xdef..."}
],
"threshold": 2
}
Test Authentication
Verify with a balances endpoint.
Role-Based Access Control
Assign roles to users or API keys for fine-grained permissions.
| Role | Permissions | Use Case |
|---|---|---|
| Viewer | balances:read, ledger:read | Auditors |
| Approver | transactions:approve | Signers |
| Admin | All actions | Platform owners |
Assign via dashboard: viewer, approver, admin.
Environment Setup
Set environment variables for secure API calls.
export V3_API_KEY="your-api-key-here"
export V3_BASE_URL="https://api.example.com"
const apiKey = process.env.V3_API_KEY;
const baseUrl = process.env.V3_BASE_URL || 'https://api.example.com';
import os
api_key = os.getenv('V3_API_KEY')
base_url = os.getenv('V3_BASE_URL', 'https://api.example.com')
Refresh and Rotate Credentials
Rotate keys monthly or after incidents. MPC signers rotate shares without downtime.
Revoke old keys immediately after rotation. Monitor logs for unauthorized access attempts.
- Generate new key/signer in dashboard.
- Update integrations.
- Revoke old credentials.
- Test endpoints.