Authentication
Bearer API keys and the scopes that limit them.
Every request to /api/v1/key/* carries an API key in the Authorization header:
Authorization: Bearer afk_xxxxxxxxxxxxxxxxxxxxxxxxA missing, malformed, expired or revoked key returns 401. Use HTTPS only: a key sent over plain HTTP should be treated as leaked.
Scopes
A key can only do what its scopes allow. Scopes are named resource:action, and an endpoint that needs one returns 403 when the key lacks it. The API reference shows the required scope on every endpoint.
| Scope | Allows |
|---|---|
products:read | List and read products. |
products:write | Create and edit products, and submit them for review. |
products:delete | Delete products. |
brands:read | List and read your brands. |
brands:write | Edit your own brands. |
requests:read | List and read buyer requests and their messages. |
requests:write | Reply to requests and change their status. |
uploads:write | Upload images, files and 3D models. |
analytics:read | Read analytics for your catalogue. |
team:read | Read members and pending invitations. |
webhooks:read | List webhook endpoints and deliveries. |
webhooks:write | Create, change and delete webhook endpoints. |
GET /whoami needs no scope: it works with any valid key.
Approved scopes cap a key
A key can carry only scopes that its integration client was approved for. To add a scope later, update the client and wait for an admin to approve the change.
Owners
A key belongs to an owner, reported by whoami:
provider: a vendor workspace. The key sees and changes only that vendor's brands, products and requests. This is what you get from an integration client.platform: keys created by ArchFindr staff. They are limited torequests:readandproducts:readacross all vendors.
A key also stops working if its owner loses the right to manage settings.
Key hygiene
- Give each system its own key so you can revoke one without touching the others.
- Set an expiry for keys used in short projects, and rotate long-lived ones regularly.
- Rotating a key issues a fresh one with the same name, scopes and lifetime, and the old one stops working immediately.
- Revoke a key the moment you suspect it leaked.