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

# POST /auth/login — Authenticate and Obtain a Token

> Exchange your Avalex credentials for a JWT token valid for 7 days. Include the token in the Authorization: Bearer header on all subsequent requests.

Use this endpoint to exchange your Avalex staff credentials for a signed JWT access token. The token is valid for **7 days** and must be included in the `Authorization: Bearer` header on every authenticated request. No API key or additional setup is required — a valid username and password are all you need to get started.

```http theme={null}
POST https://api.avalex.com/auth/login
```

<Note>
  This is a public endpoint. No authentication header is required to call it.
</Note>

## Request Body

<ParamField body="username" type="string" required>
  Your staff account username as registered in the Avalex Admin Portal.
</ParamField>

<ParamField body="password" type="string" required>
  Your account password.
</ParamField>

### Request Example

```bash theme={null}
curl -X POST https://api.avalex.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "ada", "password": "a-strong-password"}'
```

## Response — 200 OK

A successful login returns a JWT token alongside a summary of the authenticated user's identity and permissions.

<ResponseField name="token" type="string">
  A signed JWT access token. Include this value in the `Authorization: Bearer <token>` header on all subsequent authenticated requests. Tokens expire after **7 days**.
</ResponseField>

<ResponseField name="user" type="object">
  Details about the currently authenticated user.

  <Expandable title="user fields">
    <ResponseField name="username" type="string">
      The username of the authenticated staff account.
    </ResponseField>

    <ResponseField name="isMasterAdmin" type="boolean">
      `true` if this account is the Master Admin; `false` for all other roles.
    </ResponseField>

    <ResponseField name="permissions" type="string[]">
      An array of permission strings granted to this account, such as `customers:read` or `licenses:write`. Use these values to determine which API operations your token can perform.
    </ResponseField>

    <ResponseField name="role" type="string">
      The name of the role assigned to this account, for example `Support` or `Admin`.
    </ResponseField>
  </Expandable>
</ResponseField>

### Response Example

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "username": "ada",
    "isMasterAdmin": false,
    "permissions": ["customers:read", "customers:write"],
    "role": "Support"
  }
}
```

## Error Responses

| Status             | Body                                        | Description                                                      |
| ------------------ | ------------------------------------------- | ---------------------------------------------------------------- |
| `401 Unauthorized` | `{"error": "Invalid username or password"}` | The provided credentials did not match any active staff account. |

<Warning>
  Repeated failed login attempts may indicate a compromised credential. If you believe your account has been accessed without authorization, contact your Master Admin immediately to rotate your password.
</Warning>

## Notes

<Note>
  This endpoint is also available as `POST /staff/login`, which is an aliased route with identical behavior. Both paths accept the same request body and return the same response schema.
</Note>