Authentication
The Docyard API uses Bearer token authentication. Include your API key in the Authorization header of every request.
Making Authenticated Requests
curl https://api.docyard.io/v1/docks \
-H "Authorization: Bearer dk_live_a1b2c3d4e5f6..."
API Key Types
| Key Type | Prefix | Usage |
|---|
| Live | dk_live_ | Production environment |
| Test | dk_test_ | Sandbox environment |
API keys carry full access to your account. Never expose them in client-side code, public repositories, or logs. Use environment variables or a secrets manager.
Key Management
API keys are managed from the Docyard Dashboard. You can:
- Create keys with optional expiration dates
- Rotate keys without downtime (both old and new keys work during a grace period)
- Revoke keys immediately if compromised
Institutional Recipients (STS Token Exchange)
For machine-to-machine integrations, institutional recipients authenticate via STS token exchange rather than API keys:
- The institution presents credentials to the token endpoint
- Docyard returns a short-lived access token
- The token is used for retrieval API calls
# Step 1: Exchange credentials for a token
curl -X POST https://api.docyard.io/v1/auth/token \
-H "Content-Type: application/json" \
-d '{
"grant_type": "client_credentials",
"client_id": "inst_01HQ3K...",
"client_secret": "sk_live_..."
}'
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600
}
Error Responses
If authentication fails, the API returns a 401 status code:
{
"statusCode": 401,
"message": "Invalid or expired API key",
"error": "Unauthorized"
}
- Missing
Authorization header
- Malformed token (ensure the
Bearer prefix is included)
- Expired or revoked API key
- Using a test key against the production environment
Rate Limits
| Plan | Requests/minute | Burst |
|---|
| Starter | 60 | 10 |
| Professional | 600 | 100 |
| Enterprise | Custom | Custom |
429 Too Many Requests with a Retry-After header.
