> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talescria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> OAuth clients, access tokens and scopes.

The API uses the OAuth 2 **client credentials** grant. Your server holds an OAuth client's ID and secret, exchanges them for a short-lived access token, and sends that token on every request.

```http theme={null}
Authorization: Bearer at_test_…
```

## OAuth clients

Create clients in the dashboard under **Settings → OAuth clients**. Each client has:

* **An environment**, test or live, fixed when it's made. Its tokens can only act in that environment. See [Environments](https://docs.talescria.com/concepts/environments.md).
* **Scopes**: what its tokens may do. You can change them later; removing a scope stops existing tokens using it on their next request.
* **A secret** (`sk_test_…` or `sk_live_…`), shown once when the client is created or its secret is rotated. Keep it on your server. Never put it in a browser, a mobile app or source control.

You can **rotate** a client's secret (the old one stops working immediately) or **revoke** the client, which ends every token it issued.

## Getting a token

`POST https://idp.talescria.com/oauth/token` with `grant_type=client_credentials`. Authenticate with HTTP Basic (`client_id:client_secret`), or send `client_id` and `client_secret` in the form body, but not both.

```bash curl theme={null}
curl https://idp.talescria.com/oauth/token \
  -u "$TALESCRIA_CLIENT_ID:$TALESCRIA_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d "scope=accounts:read payments:read"
```

```python Python theme={null}
resp = requests.post(
    "https://idp.talescria.com/oauth/token",
    auth=(client_id, client_secret),
    data={"grant_type": "client_credentials", "scope": "accounts:read payments:read"},
    timeout=30,
)
token = resp.json()
```

| Field | Description |
| - | - |
| `access_token` | `at_test_…` or `at_live_…`. Send it as a bearer token. |
| `expires_in` | Seconds until it expires: 900 (15 minutes). |
| `refresh_token` | `rt_test_…` or `rt_live_…`. Lasts 30 days. |
| `scope` | The scopes this token carries, space-separated. |

`scope` is optional. Leave it out to get every scope the client holds, or list fewer to get a token that can do less than its client. Asking for a scope the client doesn't hold is `invalid_scope`.

### Refreshing

When an access token expires, either request a new one with client credentials or use the refresh token. Refreshing also needs the client's credentials.

```bash theme={null}
curl https://idp.talescria.com/oauth/token \
  -u "$TALESCRIA_CLIENT_ID:$TALESCRIA_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"
```

Each refresh returns a **new** refresh token. Use the new one next time: presenting a refresh token that has already been used is treated as theft, and every token descended from it is revoked.

> [!TIP]
>
> The simplest approach for a server is to cache the access token and fetch a new one with client credentials shortly before `expires_in` runs out.

## Scopes

`write` includes `read` for the same resource.

| Scope | Allows |
| - | - |
| `accounts:read` | See accounts and their balances. |
| `accounts:write` | Open new accounts. |
| `recipients:read` | See recipients and their destinations; read destination requirements and banks. |
| `recipients:write` | Add recipients and destinations. |
| `payments:read` | See payments to recipients, FX quotes and payment reasons. |
| `payments:write` | Send money to recipients and create FX quotes. **Moves money.** |
| `transfers:read` | See transfers between your own accounts. |
| `transfers:write` | Move money between your own accounts. **Moves money.** |
| `payment_links:read` | See payment links and what they've taken. |
| `payment_links:write` | Create and archive payment links. |
| `checkout:write` | Start checkout sessions that take card payments. |
| `customers:read` | See your customers. |
| `customers:write` | Add, edit and delete customers. |
| `invoices:read` | See invoices and recurring series. |
| `invoices:write` | Issue, send and void invoices, and set up recurring series. |

Give each client only what it needs. A reporting job needs read scopes; only the service that pays people needs `payments:write`.

## When a request is refused

| Status | Code | Meaning |
| - | - | - |
| `401` | `UNAUTHENTICATED` | The token is missing, expired or revoked, or its client was revoked. Get a new token. |
| `403` | `INSUFFICIENT_SCOPE` | The token is valid but lacks a scope. The scope is named in `message` and in the `WWW-Authenticate` header. |
| `403` | `ENVIRONMENT_MISMATCH` | The request named the other environment. |
| `403` | `FORBIDDEN` | The operation is only available in the dashboard. |

A `401` means "we don't know who you are" and a `403` means "we do, and this isn't allowed". Handle them separately: retrying a `403` with a fresh token won't help.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.