# Authentication

Create REST API credentials, request tokens and manage permissions.

Source: <https://docs.finbar.com/api-mcp/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](https://docs.finbar.com/api-mcp/mcp.md).

## Create a credential

1. Open the **API** panel in the [Finbar web app](https://app.finbar.com/).
2. Select **Create credential**, enter a name and choose **REST API**.
3. 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, documents and
datasets:

```bash
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_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.

| Response field | Meaning                             |
| -------------- | ----------------------------------- |
| `access_token` | The token to send with API requests |
| `token_type`   | The authorization type, `Bearer`    |
| `expires_in`   | Token lifetime in seconds           |

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

```text
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:

| Full scope name                         | Allows                                            |
| --------------------------------------- | ------------------------------------------------- |
| `https://api.finbar.com/entities:read`  | Search for companies and read company information |
| `https://api.finbar.com/documents:read` | List, search and read documents                   |
| `https://api.finbar.com/datasets:read`  | Discover and query financial datasets             |
| `https://api.finbar.com/usage:read`     | Read account usage and limits                     |

Other pages use short names such as `datasets:read` for readability. A scope
must already be granted to the credential before its tokens can request it.
Permissions do not extend your account's data coverage or allowances.

## 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](https://docs.finbar.com/api-mcp/api.md) to make a request, or
[errors and pagination](https://docs.finbar.com/api-mcp/errors.md) to handle failures in your application.