API authentication

The API base URL, how a client gets an access token, and the headers every API call needs.

Programs call the Vigilfield API with an OAuth 2.0 access token obtained through the client-credentials grant. You need a client id and secret first: see Apps, installations and clients.

Base URL

Each organization has its own address. The API lives under /api/v1 on it:

https://<your-org>.vigilfield.com/api/v1

<your-org> is your organization's slug, the first part of the address you use to sign in to Vigilfield. Every path in the API reference is relative to this base URL. For example, GET /tables is https://<your-org>.vigilfield.com/api/v1/tables.

Get an access token

Send the client id and secret to the token endpoint as a form post:

curl -X POST "https://<your-org>.vigilfield.com/api/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=client_credentials \
  -d client_id="$VF_CLIENT_ID" \
  -d client_secret="$VF_CLIENT_SECRET"

You can send the id and secret with HTTP Basic authentication instead of in the body. If both are present, Basic wins.

A successful response:

{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "tables:read"
}

The token is a signed JWT and lasts 900 seconds (15 minutes).
There is no refresh token. When a token expires, request a new one the same way.
scope lists what the token may do: the client's scopes, narrowed to what its installation currently grants.

Asking for fewer scopes

Add scope to the form with a space-separated list, for example scope=tables:read. The token then carries only those scopes. Asking for a scope the client does not hold fails with invalid_scope. Without scope, you get everything the client holds.

Discovery

Standard OAuth metadata is published at:

https://<your-org>.vigilfield.com/api/v1/.well-known/oauth-authorization-server
https://<your-org>.vigilfield.com/api/v1/.well-known/jwks.json (the public signing keys)

Token errors

Status	`error`	Meaning
400	`invalid_request`	`client_id` or `client_secret` is missing.
401	`invalid_client`	Unknown client or wrong secret. The response does not say which.
400	`invalid_scope`	A requested scope is malformed or beyond what the client holds.
400	`unsupported_grant_type`	`grant_type` is not `client_credentials`.
500	`server_error`	The token could not be issued. Retry later.

Call the API

Every authenticated request needs two headers:

Authorization: Bearer <access_token>
x-vf-team-id: <team-id> — the team the request acts as. For a client, this is the team that installed its app. A missing header returns 400; a team the caller is not on returns 403.

curl "https://<your-org>.vigilfield.com/api/v1/tables" \
  -H "Authorization: Bearer $VF_TOKEN" \
  -H "x-vf-team-id: $VF_TEAM_ID"

You can find the team id as team_id on the installation, from List installations.

You may also send x-vf-org-id. It is optional, but if you send it, it must match the token's organization or the request is refused with 403.

A token's scopes are an upper bound. Each request is still checked against the installation's grants on the specific resource, so a token with tables:read can read only the tables the installation was granted.

Revoke a token

To stop one issued token before it expires, post it to the revocation endpoint. The request itself must be authenticated like any other API call:

curl -X POST "https://<your-org>.vigilfield.com/api/v1/oauth/revoke" \
  -H "Authorization: Bearer $VF_TOKEN" \
  -H "x-vf-team-id: $VF_TEAM_ID" \
  -d token="$TOKEN_TO_REVOKE"

The answer is 200 whether or not the token was valid. Revocation stops one token. It does not stop the client from getting new ones.

If a client secret leaks, delete the client first so it cannot get new tokens. Tokens it already has stay valid for up to 15 minutes unless you revoke each one. Uninstalling the app from the team stops all of that installation's tokens at once, but it also deletes all of the installation's clients.