Authentication
API keys
Keys are created by Space admins in app.gatevia.app → Settings → API keys and look like:
gv_live_1nX8vQ2pL5aT9cB0dE3fG6hJ7kM4nP8rS1tU5vW9- Per Space — a key belongs to one Space and cannot see any other.
- Shown once — GateVia stores only a SHA-256 hash. Losing the secret means revoking the key and creating a new one.
- Identified by prefix — the dashboard shows
gv_live_1nX8…so you can tell keys apart without ever seeing the secret again. - Create one key per integration so each can be scoped, monitored (last-used timestamp) and revoked independently.
Sending the key
Preferred:
Authorization: Bearer gv_live_…Also accepted: X-Api-Key: gv_live_…
Scopes
Every key carries an explicit set of permissions:
| Scope | Grants |
|---|---|
gates:read | List gates |
gates:write | Create, update, deactivate gates |
gates:open | Physically open gates — opt-in, use with care |
members:read | List members and their accesses |
members:write | Create/update members, grant/edit/revoke gate access |
history:read | Read openings and the activity log |
Calling an endpoint without the needed scope returns 403
insufficient_scope.
Rate limits
- Default: 120 requests/minute per key.
- Writes: 30/minute.
POST /gates/:id/open: 10/minute. - Exceeding the limit returns 429 with a
Retry-Afterheader.
Errors
All errors share one shape:
{ "error": { "code": "not_found", "message": "Gate not found in this Space." } }| HTTP | code | Meaning |
|---|---|---|
| 400 | validation_error | Body failed schema validation |
| 401 | unauthorized | Missing/invalid/revoked/expired key |
| 403 | insufficient_scope | Key lacks the required scope |
| 403 | plan_upgrade_required | Plan does not include API access |
| 403 | plan_limit_reached | Plan limit (gates, invitations…) reached |
| 404 | not_found | Resource missing or not in this Space |
| 429 | — | Rate limit exceeded |
| 5xx | internal_error | Our fault — retry with backoff |