API
Authentication
Use an API key for each system you connect. Choose read-only access or allow it to make changes.
Check your key
/me200 with key { name: string, canWrite: boolean } and organization { id: string, name: string, reportingTimeZone: string }.Use HTTPS and the base path /api/partner/v1. Firebase sign-in tokens do not authenticate these endpoints; API keys do not sign a person in to Viffy.
API keys
Send the key as a bearer token on every request.
Authorization: Bearer vfy_AbC123XyZ789_...- Create keys under Settings → API access and store them on your server. The full key is shown once.
- An organization can have up to 20 active keys. Revoking a key stops its access immediately; further calls return
401 unauthenticated. - To rotate, create a new key, switch to it, then revoke the old one.
Read-only keys
New keys default to Read only. Clear that checkbox when creating a key that needs to add or change data.
A read-only key receives 403 forbidden on POST, PUT, PATCH, and DELETE. Check key.canWrite in GET /me to confirm access.
You cannot change a key’s access level later. Create a replacement key if it needs different access.
Organizations
Keys created in Viffy currently open one organization, named by GET /me. No organization header is needed for those keys. If a key has been granted access to several, name one per request:
X-Organization-Id: 2f6d1c2e-9c3a-4b7e-8f21-0a1b2c3d4e5f| Situation | Answer |
|---|---|
| Key opens one organization, header absent | Acts for that organization. |
| Key opens several, header absent | 400 validation_failed. Name one. |
| Header names an organization the key cannot act for | 403 forbidden |
Rate limits
In production, each key may make 600 requests a minute; shared service limits also apply. Beyond that the answer is 429 rate_limited with a Retry-After header saying how many seconds to wait.
Request IDs
Every response carries a Viffy-Request-Id header. Log it, and quote it when you contact support about a request.
Keep the key out of the client
An API key grants access to your organization’s data. Keep it on your server and have your app call your server; do not include it in browser code, app bundles, URLs, or logs.