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

# zkID API

> API reference for zkID identity operations

## Register

Create a new privacy-preserving zkID identity.

```bash theme={null}
POST /api/auth/register
```

**Request:**

```json theme={null}
{
  "username": "alice",
  "password": "secure_password_123",
  "identityPublicKey": "base64_public_key",
  "identityPrivateKeyEncrypted": "base64_encrypted",
  "identityPrivateKeyIv": "base64_iv",
  "kdfSalt": "base64_salt",
  "kdfIterations": 200000
}
```

**Response:**

```json theme={null}
{
  "message": "zkID created successfully",
  "user": {
    "id": "uuid",
    "username": "alice",
    "zkId": "did:zk:a7Bk9mX2pQ4r",
    "identityPublicKey": "base64_public_key"
  }
}
```

***

## Login

Authenticate using zkID credentials.

```bash theme={null}
POST /api/auth/login
```

**Request:**

```json theme={null}
{
  "username": "alice",
  "password": "secure_password_123"
}
```

**Response:**

```json theme={null}
{
  "message": "Login successful",
  "user": {
    "id": "uuid",
    "username": "alice",
    "zkId": "did:zk:a7Bk9mX2pQ4r"
  }
}
```

***

## Logout

End the current session.

```bash theme={null}
POST /api/auth/logout
```

**Response:**

```json theme={null}
{
  "message": "Logged out successfully"
}
```

***

## Get Session

Check current authentication status.

```bash theme={null}
GET /api/auth/session
```

**Response (authenticated):**

```json theme={null}
{
  "authenticated": true,
  "user": {
    "id": "uuid",
    "username": "alice",
    "zkId": "did:zk:a7Bk9mX2pQ4r",
    "identityPublicKey": "base64_public_key"
  }
}
```

**Response (not authenticated):**

```json theme={null}
{
  "authenticated": false
}
```

***

## Upgrade Legacy Account

Upgrade account without zkID to full zkID verification.

```bash theme={null}
POST /api/auth/upgrade-legacy
```

**Request:**

```json theme={null}
{
  "identityPublicKey": "base64_public_key",
  "identityPrivateKeyEncrypted": "base64_encrypted",
  "identityPrivateKeyIv": "base64_iv",
  "kdfSalt": "base64_salt",
  "kdfIterations": 200000
}
```

***

## Submit Starknet Proof

Submit zkID proof to Starknet for on-chain verification.

```bash theme={null}
POST /api/starknet/submit-proof
```

**Request:**

```json theme={null}
{
  "zkId": "did:zk:a7Bk9mX2pQ4r",
  "publicKey": "base64_public_key",
  "signature": "base64_signature"
}
```

**Response:**

```json theme={null}
{
  "success": true,
  "txHash": "0x123...",
  "contractAddress": "0x456..."
}
```

***

## Error Codes

| Code | Description             |
| ---- | ----------------------- |
| 400  | Username already exists |
| 401  | Invalid credentials     |
| 401  | Not authenticated       |
| 409  | Proof already exists    |
| 500  | Failed to create zkID   |