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

# Authentication Lifecycle

> How DalySDK obtains, caches, refreshes, and retries bearer auth

# Authentication Lifecycle

DalySDK uses workspace + user API keys to obtain a JWT from DalyAPI.

## Token Acquisition

On first authenticated request, the SDK calls:

* `POST /auth/token`

with payload:

```json theme={null}
{
  "workspace_id": "WORKSPACE_API_KEY",
  "user_id": "USER_API_KEY"
}
```

## Token Caching and Refresh

`AuthManager` caches:

* token value
* token expiry timestamp

Refresh is triggered when token is missing or within 1 hour of expiry.

## 401 Retry Behavior

For API requests:

1. SDK sends request with current token.
2. If response is `401`, SDK invalidates token.
3. SDK refreshes token and retries once.
4. If retry still fails, `AuthenticationError` is raised.

## Failure Modes

`AuthenticationError` is raised for:

* Invalid API keys (`401` from auth endpoint)
* Non-200 auth responses
* Network errors reaching auth endpoint
* Missing token field in auth response

<Warning>
  Workspace and user API keys are root credentials for token exchange. Keep them in secure secret storage.
</Warning>