API introduction

The API base URL is https://api.finbar.com/v1. This guide uses curl to make requests from a terminal. For account requirements, see API and MCP.

1. Create a credential

Open the API panel in the Finbar web app. Select Create credential, enter a name and choose REST API.

Save the Client ID and Client secret. The secret is shown only when it is created or replaced. Keep it in your application's secret storage, outside source code and browser applications.

2. Get an access token

In this example, CLIENT_ID and CLIENT_SECRET contain the values you saved. Request a token with permission to find companies, read documents and query datasets:

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

The --config - option reads the credentials from standard input, keeping the client secret out of the command's argument list.

The response includes access_token, token_type and expires_in. The last field is the token's lifetime in seconds. Store the access token as ACCESS_TOKEN for the examples below. Reuse it until it approaches expiry, then request another token with the same client ID and secret.

3. Find a company

curl --fail-with-body --silent --show-error --get \
  'https://api.finbar.com/v1/entities' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode 'q=Apple' \
  --data-urlencode 'limit=5'

The response's entities array contains matching companies. Check the company name and save its entity_id for later requests. An empty array means there are no available matches for that search.

Next, list the company's documents or discover its financial dataset.

Request only the permissions you need

The token request's scope field is a space-separated list of permissions. Use the full permission name, including the URL prefix:

A permission must be available on the credential before a token can request it. REST API credentials and tokens are separate from MCP connections.

Replace or revoke a credential

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.