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

# Authentication

> DID challenge flow and JWT usage

# Authentication

Fortro Engine authenticates clients with DID-bound signatures and returns a JWT for subsequent API calls.

## Flow

```mermaid theme={null}
sequenceDiagram
    participant C as Client
    participant F as Fortro Engine
    C->>F: POST /api/auth/challenge { did }
    F-->>C: challenge, expires_at
    C->>C: Sign challenge with local DID key
    C->>F: POST /api/auth/verify-challenge { did, challenge, signature }
    F-->>C: user, token
```

`POST /api/auth/login` accepts the same `did`, `challenge`, and `signature` body and also returns `user` plus `token`.

## Required Headers

Use the issued JWT for protected routes:

```http theme={null}
Authorization: Bearer <jwt>
X-User-DID: did:alyra:...
```

Issuer and verifier calls usually also include the active DID as a path parameter:

```http theme={null}
POST /api/issuer/:did/schemas
GET /api/verifier/:did/presentations
```

## Auth Endpoints

| Method | Path                         | Purpose                                        |
| ------ | ---------------------------- | ---------------------------------------------- |
| `POST` | `/api/auth/register`         | Register a DID and public key.                 |
| `POST` | `/api/auth/login`            | Verify challenge signature and issue JWT.      |
| `POST` | `/api/auth/challenge`        | Create a challenge for a DID.                  |
| `POST` | `/api/auth/verify-challenge` | Verify challenge signature and issue JWT.      |
| `POST` | `/api/auth/generate-did`     | Generate a DID, optionally from a private key. |
| `GET`  | `/api/auth/me`               | Return the current authenticated user.         |
| `GET`  | `/api/auth/profile`          | Return profile data for the authenticated DID. |
| `PUT`  | `/api/auth/profile`          | Update profile data.                           |
| `POST` | `/api/auth/avatar`           | Upload a profile avatar.                       |
| `POST` | `/api/auth/create-wallet`    | Create wallet auth metadata.                   |
| `POST` | `/api/auth/login-wallet`     | Login with wallet auth metadata.               |

<Note>
  Client applications still protect seed material locally with their own PIN and recovery flows. The backend auth contract is the DID challenge signature plus JWT.
</Note>