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

# Authentication

> Authentication model for the YouNegotiate API 2.0 reference.

Most API endpoints use bearer token authentication.

```http theme={"system"}
Authorization: Bearer <access-token>
Accept: application/json
```

Authentication endpoints issue tokens for the matching portal domain. Each portal API should be documented separately so the playground uses the correct base URL and token context.

## Access And Refresh Tokens

Normal login, registration, creditor email verification, consumer OTP verification, and trusted-device login responses include token metadata:

* `meta.access_token` is the Sanctum bearer token used on authenticated API calls.
* `meta.refresh_token` is a plaintext refresh token returned once. Store it securely and send it to `POST /auth/refresh` when a new access token is needed.
* `meta.token_type` is `Bearer`.
* `meta.access_token_expires_at` is the access-token expiry timestamp when an expiry is assigned; otherwise it is `null`.
* `meta.refresh_token_expires_at` is the refresh-token expiry timestamp.

Creditor, Superadmin, and EcoMail Hub login endpoints accept optional `remember`. Omitted or `true` uses the remembered refresh-token TTL, which defaults to 30 days. `remember: false` uses the standard refresh-token TTL, which defaults to 12 hours. Refresh rotation keeps the original remember mode.

`POST /auth/refresh` rotates both tokens. A successful refresh revokes the old refresh token, deletes the old linked Sanctum access token, and returns replacement token metadata. Expired, revoked, malformed, or reused refresh tokens return `401`.

## Superadmin Login-As Handoffs

Superadmin login-as uses a two-step handoff so target-portal credentials are never returned from the Superadmin domain:

1. The authenticated Superadmin endpoint creates an 80-character handoff token and expiry timestamp. No access or refresh token is included in this response.
2. The frontend immediately sends the handoff token in the JSON body of `POST /auth/login-as/exchange` on the target Creditor or EcoMail Hub API.
3. A successful exchange consumes the handoff and returns a non-remembered access and refresh token pair for the target user.

Handoffs are single-use, default to a 60-second lifetime, and only work on the portal for which they were issued. Invalid, expired, reused, wrong-portal, deleted-user, and ineligible-creditor handoffs return `422` with the same generic validation message. Their refresh-token TTL follows the standard non-remembered duration.

Treat the plaintext handoff like a credential: keep it only in memory, never place it in a URL, and discard it after exchange.

## Token Scope

| Portal          | Token Context              |
| --------------- | -------------------------- |
| Creditor API    | Creditor company user      |
| Consumer API    | Consumer account           |
| Super Admin API | Platform admin user        |
| EcoMail Hub API | Mail response manager user |