Authentication

REST API requests use an access token, a temporary credential sent with each request. Your application obtains it using a client ID and client secret, the credential pair you create in Finbar.

This is the OAuth client credentials flow: the application authenticates using its own credentials without asking a person to sign in for each request. MCP assistants use a separate browser sign-in flow.

Create a credential

1. Open the API panel in the Finbar web app.
2. Select Create credential, enter a name and choose REST API.
3. Choose Read only or Read & write. Read/write access also permits paid jobs.
4. Save the Client ID and Client secret. The secret is shown only when created or replaced.

Keep the secret in your application's secret storage. Use it in server-side code or scripts, not browser applications or source control.

Request an access token

The following command assumes CLIENT_ID and CLIENT_SECRET contain your saved credentials. It requests permission to read companies and documents and to run paid Build/Update Dataset jobs:

curl --fail-with-body --silent --show-error \
  --config - \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=https://api.finbar.com/read https://api.finbar.com/write' \
  https://auth.finbar.com/oauth2/token <<EOF_TOKEN
user = "$CLIENT_ID:$CLIENT_SECRET"
EOF_TOKEN

--config - reads the credentials from standard input so the client secret is not included in the command's argument list.

Store access_token as ACCESS_TOKEN for the examples in these docs. Send it in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Reuse the token until it approaches expiry, then request another using the same client ID and secret. A token issued for MCP cannot be used for the REST API.

Permissions (OAuth scopes)

An OAuth scope is a named permission. The token request's scope field is a space-separated list of those permissions. Request the full names below, including the URL prefix:

Use read for read-only access. For read/write access, request both read and write, as in the token example above. Other guides use these short names; Cognito token requests need the full names in the table.

New API features use these permissions, so adding a feature does not require a new credential. Your account's data access, plan limits, and AI charges still apply. MCP uses the same permission names with its own resource prefix; REST and MCP tokens are not interchangeable.

Omitting scope is supported: the token receives all scopes enabled for that credential. Explicitly requesting the full REST scope names above keeps your integration's requested permissions predictable.

Migration on 29 October 2026

The per-resource scopes, such as entities:read and documents:read, were replaced by read and write on 29 October 2026. Existing credentials were migrated without changing their client IDs or secrets. Update any explicit token request to the full scope names above. Old scope names return 400 invalid_scope; retrying the same scope will not resolve the error.

The token endpoint's OAuth errors are separate from REST API errors. Correct invalid_scope requests before retrying. Use backoff for temporary failures and reuse tokens until they approach expiry.

Rotate or revoke credentials

Use Rotate in the API panel to replace a credential. Update your application with both the new client ID and secret. The previous pair stops issuing tokens.

Use Revoke when a credential is no longer needed. If an existing credential lacks a permission you need, create a replacement with that permission; rotation preserves the existing permissions.

Continue with the API quickstart to make a request, or errors and pagination to handle failures in your application.