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

# Authenticate with the QuanuX REST API

> Obtain a bearer token from the QuanuX API, register API clients, and pass credentials in requests to the Foundry, strategy, and integration endpoints.

The QuanuX server exposes a REST API on port `8080`. All endpoints that modify state or access sensitive data require a bearer token passed in the `Authorization` header. You obtain a token by logging in with your QuanuX credentials, then include it in subsequent requests.

## POST /api/auth/login

Exchange your QuanuX username and password for a bearer token.

**Request body**

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

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

<ParamField body="client_id" type="string">
  Optional. The client ID for machine-to-machine authentication. If omitted, the request authenticates as a user session.
</ParamField>

<ParamField body="client_secret" type="string">
  Optional. The client secret corresponding to `client_id`.
</ParamField>

**Response**

<ResponseField name="token" type="string">
  Bearer token to include in subsequent API requests.
</ResponseField>

<ResponseField name="user_id" type="string">
  Unique identifier for the authenticated session.
</ResponseField>

<ResponseField name="scopes" type="array">
  List of permission scopes granted to this token.
</ResponseField>

**Example**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://localhost:8080/api/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "username": "your_username",
      "password": "your_password"
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "http://localhost:8080/api/auth/login",
      json={"username": "your_username", "password": "your_password"}
  )
  token = resp.json()["token"]
  ```
</CodeGroup>

```json Response theme={null}
{
  "token": "eyJ...",
  "user_id": "user_abc123",
  "scopes": ["strategy:read", "strategy:write", "forge:write"]
}
```

## Using the token

Pass the token in the `Authorization` header for all subsequent API requests:

```bash theme={null}
curl -X POST http://localhost:8080/api/foundry/forge \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{ "component_type": "strategy", "name": "MyStrategy", "target_lang": "python" }'
```

## POST /api/auth/register-client

Register a named API client for machine-to-machine access. Use this when you want to grant a service or script its own credentials rather than using your personal account token.

**Request body**

<ParamField body="client_name" type="string" required>
  A human-readable name for the client (e.g., `"backtest-runner"` or `"ci-pipeline"`).
</ParamField>

<ParamField body="email" type="string">
  Optional. Contact email associated with this client.
</ParamField>

**Response**

<ResponseField name="client_id" type="string">
  The generated client ID. Use this as `client_id` in `/api/auth/login` requests.
</ResponseField>

<ResponseField name="client_secret" type="string">
  The generated client secret. Store this securely — it is only shown once.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

**Example**

```bash theme={null}
curl -X POST http://localhost:8080/api/auth/register-client \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "backtest-runner" }'
```

```json Response theme={null}
{
  "client_id": "client_a3f9c2d1",
  "client_secret": "secret_b4e8a1c7d3f2e901",
  "message": "Client 'backtest-runner' registered successfully."
}
```

<Warning>
  The `client_secret` is returned only at registration time. Store it in your OS keyring with `quanuxctl secrets set` — it cannot be retrieved again.
</Warning>

## Common authentication errors

| Status             | Meaning                                                                |
| ------------------ | ---------------------------------------------------------------------- |
| `401 Unauthorized` | Invalid username, password, or client credentials                      |
| `403 Forbidden`    | Token is valid but lacks the required scope for the requested endpoint |