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

# Authentication

> How dashboard users and tenant apps authenticate against the current backend.

TrueParser separates human dashboard access from machine access used by tenant apps and the Demo UI.

## Authentication Model

There are two main authentication paths:

1. dashboard sign-in for tenant users
2. machine-to-machine token issuance for tenant apps

## 1. Dashboard Sign-In

The dashboard is used to manage tenants, apps, plans, storage, and billing.

* **URL**: `https://dashboard.trueparser.com`
* **Users**: tenant users
* **Current host setup**: Google authentication is configured in the host

This is the management side of the control plane.

## 2. Machine Access For Tenant Apps

Backend services and the Demo UI authenticate by exchanging app credentials for an access token.

* **Token endpoint**: `https://admin-api.trueparser.com/connect/token`
* **Identity**: tenant application
* **Credentials**: `client_id` and `client_secret`
* **Flow**: OAuth 2.0 `client_credentials`

### Requesting A Token

```bash theme={null}
curl -X POST https://admin-api.trueparser.com/connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=TrueParser.API"
```

### Access Token Lifetime

The access token lifetime is configured to 15 minutes.

<Tip>
  A 15-minute access token should not be a bottleneck for M2M clients if your
  backend caches the token and renews it close to expiry. The usual anti-pattern
  is requesting a new token for every API call.
</Tip>

## Token Claims

For tenant apps, the access token is enriched with claims from tenant and app metadata.

Common claims include:

* `sub`
* `tenantid`
* `appId`
* `licenseRegionCode`
* `dbCode`
* `allowed_domain_1`, `allowed_domain_2`, `allowed_domain_3`
* `entitlements` when a usable plan is assigned

Example:

```json theme={null}
{
  "iss": "https://admin-api.trueparser.com",
  "sub": "your_client_id",
  "tenantid": "3f9a6c6e-...",
  "appId": "7b1c0d8c-...",
  "licenseRegionCode": "aws-us-east-1",
  "dbCode": "region-db-code",
  "allowed_domain_1": "localhost:3000",
  "entitlements": {
    "maxDocumentUnitsPerMonth": 1000,
    "advancedPdfExtraction": false,
    "ocrPdfExtraction": false
  }
}
```

## What Is Required For Token Issuance

For tenant apps, token issuance depends on app and tenant state.

* the app must exist
* the app must be enabled
* the tenant must be active
* the app must have a license region
* the app must have a stamped database code

## Plan Impact On Tokens

Plan assignment affects the `entitlements` claim.

* no plan assigned: token issuance can still succeed, but `entitlements` is omitted
* usable plan assigned: token includes `entitlements`
* retired plan assigned: token issuance is blocked

## Related Docs

* [Onboarding](/dashboard/onboarding)
* [App Setup and Credentials](/dashboard/app-setup)
* [Demo UI](/dashboard/demo-ui)
* [Billing](/dashboard/billing)