Getting started
Create an API key, send two headers, and call /v1/whoami to confirm the key works.
1. Create a key
Only an Admin or Scheduler can create an organization key.
- Sign in to your Fido organization and open Settings → API Keys.
- Select Generate an API key. In the dialog, set:
- Key name: a name you will recognize later, such as "QuickBooks sync".
- Scopes: what the key may call. Leave it empty for full access. The key still cannot do more than your own role allows.
- Expires: 30 days, 90 days (the default), 1 year, or never.
- Rate limit (requests per minute) (optional): leave it empty to use the default for the key's tier.
- Allowed IP addresses (optional): leave it empty to allow any address. If you add addresses, the key works only from those.
- Copy the key right away. Fido shows it once: "API key created. Store the token now — it will not be shown again."
- On the same page, use the copy button next to your organization ID. That value is your
X-Tenant-ID.
Revoke a key on the same page at any time to disable it.
A key acts as the person who created it. Store it in a secrets manager or an environment variable. Do not put it in a web page or a mobile app.
2. Send two headers
| Header | Value | When |
|---|---|---|
Authorization | Bearer <your key> | Every request. |
X-Tenant-ID | Your organization ID, for example TNT-AB12CD34 | Required for organization and user keys. Platform keys can leave it out. |
Send requests to api.fetchfido.ai. Other hosts, including your organization's own Fido web address, answer 404 for these routes.
3. Make your first call
Set your key and organization ID as environment variables, then call GET /v1/whoami.
export FIDO_API_KEY="paste the key you copied"
export FIDO_TENANT_ID="paste your organization ID"
curl https://api.fetchfido.ai/v1/whoami \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID"A valid key returns HTTP 200. This example shows the shape; your values will differ.
{
"success": true,
"message": "ok",
"data": {
"user_id": "USR-EXAMPLE1",
"name": "Pat Example",
"tier": "org",
"role": "admin",
"scopes": ["*"],
"tenant_id": "TNT-AB12CD34"
}
}scopes lists what the key holds. ["*"] means full access. The response can also include entityType, entityId, clients and primaryClient. They identify the client, consumer or provider record a portal login acts as, and are empty for admins and schedulers.
/v1/whoami works with any valid key, whatever its scopes. A 401 or 403 here means the key, the organization ID or the key's settings need attention. See Errors.
4. Read some data
A key with the assignments:read scope can list assignments:
curl https://api.fetchfido.ai/v1/assignments \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID"The API reference lists the filters and the response for each endpoint.
Next: Keys and scopes explains the key tiers and what each scope allows.