> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.umnai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.umnai.com/_mcp/server.

# Authentication

Most API requests require an access token.

Your integration gets an access token by exchanging API credentials at the authentication endpoint. It then sends that token as a bearer token on subsequent requests.

```bash
Authorization: Bearer ACCESS_TOKEN
```

## How authentication works

Authentication separates long-lived credentials from short-lived access tokens.

API credentials identify the account or user your integration acts as. Access tokens authorise individual API requests and expire after a limited time.

To authenticate:

1. create or obtain API credentials;
2. exchange those credentials at `POST /oauth/token`; and
3. use the returned `access_token` in the `Authorization` header.

You need permission to create credentials in the dashboard, or you need credentials issued by someone with the right access.

## Choose a credential type

For most backend integrations and automation workloads, use [account credentials](./account-api-credentials). They are scoped to an account and are the safest default when your integration does not need to act as a specific user.

Use [user credentials](./user-api-credentials) when API actions need to be attributed to a user, or when the workflow needs the organisations and accounts available to that user.

| Credential type     | Best for                                                                                     |
| ------------------- | -------------------------------------------------------------------------------------------- |
| Account credentials | Backend services, scheduled workflows, and account-scoped automation.                        |
| User credentials    | User-scoped automation, administrative workflows, and actions that require user attribution. |

## Token exchange

Both credential types use the same authentication endpoint.

Account credentials use `grant_type: "client_credentials"` with a `client_id` and `client_secret`.

User credentials use `grant_type: "user_token"` with a user token and secret.

See [Account credentials](./account-api-credentials) or [User credentials](./user-api-credentials) for the exact request examples.