Getting started

How to obtain an API token, make a first authenticated request, and read the response.

Three steps: issue a token, call an endpoint with it, read the envelope back.

1. Issue a token

Tokens are created in the platform UI, signed in as a user — not through this API. Open the API tokens screen for your team, choose the scopes the integration needs, and create.

You cannot mint a token with a token. Token management lives at /v1/api-tokens, and that path is deliberately not part of the public surface: an API token that could issue API tokens would be able to widen its own scopes, which is the one privilege the scope model exists to withhold.

A token looks like this:

fgd_live_a1b2c3d4e5f6789012345678abcdef01234567890abcdef1234567890abcdef

The prefix fgd_live_ is followed by 64 hex characters of cryptographically random secret.

The secret is shown exactly once

At creation, and never again. The platform stores only a SHA-256 hash of it, so there is no screen, no support request and no database query that can recover the value later. Copy it into your secret store before closing the dialog; if you lose it, rotate the token and take the new one.

A few limits worth knowing before you plan around them:

2. Make a request

Send the token as a bearer credential:

curl https://api.foxguide.io/v1/tables \
  -H 'Authorization: Bearer fgd_live_a1b2c3d4...'

The production host is https://api.foxguide.io. A staging host, https://api.stage.foxguide.io, serves the same contract against staging data.

Nothing is granted by default. A token reaches an endpoint only when its scope list names that endpoint’s entity and the action the endpoint performs — see Authentication for the model and for the refusal you will meet if a scope is missing.

3. Read the response

A single resource comes back on its own, or wrapped in data. A collection always comes back as an envelope with a pagination block:

{
  "data": [ { "id": "tbl_...", "name": "Leads" } ],
  "pagination": { "limit": 20, "offset": 0, "hasMore": true, "total": 137 }
}

Errors are flat and always the same shape:

{ "error": "INSUFFICIENT_SCOPE", "message": "API token does not have scope table:write" }

Branch on the HTTP status and on error — never on the presence of a payload. Errors covers the status codes and which of them are worth retrying; Pagination covers walking a collection.

Rotating without downtime

When a token needs replacing, rotate rather than delete-and-recreate. Rotation issues a new secret and keeps the old one valid for a 24-hour grace period, so a running integration can pick up the new value on its own schedule instead of failing between the two calls.

Where to go next

• Authentication — scopes, default-deny, and INSUFFICIENT_SCOPE
• Rate limits — what 429 means and what to do about it
• Webhooks — receiving events instead of polling for them
• API reference — every published endpoint, generated from the contract

← All documentation