Getting started
From a new integration to your first API call.
You need an ArchFindr vendor workspace and a role that can manage settings. The setup takes a few minutes, plus the time an ArchFindr admin needs to review your request.
Create an integration client
Open your vendor workspace, go to Settings, then Integrations, and create a client. Give it a name that tells your team what it is for, such as "ERP sync", and tick the scopes it needs. Ask only for what the integration will use: a read-only dashboard needs products:read and requests:read, not the write scopes.
The client is created with the status pending.
Wait for approval
An ArchFindr admin reviews the client and the scopes you asked for. They can approve all or a subset of the requested scopes, or reject the client. The status in Settings changes when the review is done.
| Status | Meaning |
|---|---|
pending | Waiting for review. No keys can be issued yet. |
approved | Keys can be issued, with up to the approved scopes. |
rejected | The request was declined. Create a new client with a narrower scope. |
revoked | An admin withdrew access. Its keys stop working. |
Create an API key
Once the client is approved, create a key from the client page. Choose a name, the scopes (any subset of what was approved) and an optional expiry.
Copy the key now
The full key, which starts with afk_, is shown once. ArchFindr stores only a hash, so a lost key cannot be recovered: rotate it to get a new one.
Keep the key in a secret manager or an environment variable. Never put it in browser code or a public repository.
Make your first request
Call whoami to check that the key works and to see its owner and scopes:
curl https://api.archfindr.com/api/v1/key/whoami \
-H "Authorization: Bearer $ARCHFINDR_API_KEY"{
"owner": { "kind": "provider", "providerId": "0198a1f2-7c3e-7d4b-9a10-5b6c8e2f1a34" },
"scopes": ["products:read", "requests:read"]
}Then list your products, 25 per page:
curl "https://api.archfindr.com/api/v1/key/products?perPage=25" \
-H "Authorization: Bearer $ARCHFINDR_API_KEY"Next steps
- Read Authentication for the scope list and key handling.
- Page through large lists with Pagination.
- Subscribe to Webhooks instead of polling.