# API Reference

## Authentication

All requests must include Token in the header:

```
Authorization: Bearer v4.local.your-token
```

Token is in PASETO v4 format, generated from the Web console's Token Management page or via `POST /api/v1/tokens` endpoint.

## Endpoint List

### Authentication

| Method | Path                  | Description                                            |
| ------ | --------------------- | ------------------------------------------------------ |
| `POST` | `/api/v1/auth/login`  | User login, returns `access_token` and `refresh_token` |
| `POST` | `/api/v1/auth/logout` | Logout, revoke current Token                           |

**Login request example:**

```json
POST /api/v1/auth/login
{
  "username": "your-username",
  "password": "your-password"
}
```

### Credential Management

| Method   | Path                              | Description                        | Required Scope       |
| -------- | --------------------------------- | ---------------------------------- | -------------------- |
| `GET`    | `/api/v1/credentials`             | List credential metadata           | `credential:read`    |
| `POST`   | `/api/v1/credentials`             | Create credential                  | `credential:write`   |
| `GET`    | `/api/v1/credentials/:id`         | Get single credential              | `credential:read`    |
| `DELETE` | `/api/v1/credentials/:id`         | Delete credential                  | `credential:write`   |
| `POST`   | `/api/v1/credentials/:id/decrypt` | Decrypt credential (TEE execution) | `credential:decrypt` |

**Create credential request example:**

```json
POST /api/v1/credentials
{
  "service_id": "schwab",
  "credential_type": "username_password",
  "plaintext_data": {
    "username": "user@example.com",
    "password": "secret"
  }
}
```

**Create zkMe Credential request example** (zkKYC shown; same structure for zkPoAI, AMLMe, zkKYA, etc.):

```json
POST /api/v1/credentials
{
  "service_id": "zkme",
  "credential_type": "zkme_credential",
  "plaintext_data": {
    "credential_json": {
      "@context": ["https://www.w3.org/2018/credentials/v1"],
      "type": ["VerifiableCredential", "ZkMeCredential"],
      "issuer": "did:zkme:issuer_xxx",
      "issuanceDate": "2026-03-01T00:00:00Z",
      "credentialSubject": {
        "id": "did:zkme:user_yyy",
        "kycStatus": "approved"
      },
      "proof": {
        "type": "Ed25519Signature2020",
        "created": "2026-03-01T00:00:00Z",
        "proofPurpose": "assertionMethod",
        "proofValue": "z58D..."
      }
    },
    "did": "did:zkme:user_yyy",
    "zk_proof": "base64_encoded_zkp...",
    "credential_type": "zkKYC"
  }
}
```

**Decrypt credential request example:**

```json
POST /api/v1/credentials/018f1b4e-.../decrypt
{
  "reason": "User initiated bank statement query"
}
```

### Token Management

| Method | Path                        | Description                                       |
| ------ | --------------------------- | ------------------------------------------------- |
| `POST` | `/api/v1/tokens`            | Generate new Token                                |
| `POST` | `/api/v1/tokens/verify`     | Verify Token validity (includes revocation check) |
| `POST` | `/api/v1/tokens/:id/revoke` | Revoke specified Token                            |

### Sandbox Session

| Method   | Path                                      | Description               | Required Scope       |
| -------- | ----------------------------------------- | ------------------------- | -------------------- |
| `POST`   | `/api/v1/sandbox/sessions`                | Create browser session    | `credential:decrypt` |
| `GET`    | `/api/v1/sandbox/sessions`                | List sessions             | `credential:read`    |
| `GET`    | `/api/v1/sandbox/sessions/:id`            | Get session details       | `credential:read`    |
| `POST`   | `/api/v1/sandbox/sessions/:id/execute`    | Execute browser operation | `credential:decrypt` |
| `POST`   | `/api/v1/sandbox/sessions/:id/screenshot` | Take screenshot           | `credential:decrypt` |
| `POST`   | `/api/v1/sandbox/sessions/:id/export`     | Export structured data    | `credential:decrypt` |
| `POST`   | `/api/v1/sandbox/sessions/:id/pause`      | Pause session             | `credential:decrypt` |
| `POST`   | `/api/v1/sandbox/sessions/:id/resume`     | Resume session            | `credential:decrypt` |
| `DELETE` | `/api/v1/sandbox/sessions/:id`            | Close and destroy session | `credential:decrypt` |

**Execute operation request example:**

```json
POST /api/v1/sandbox/sessions/session-uuid/execute
{
  "operation_type": "fill",
  "selector": "#password",
  "value": "{{CREDENTIAL.password}}"
}
```

### Audit Log

| Method | Path                            | Description                 | Required Scope |
| ------ | ------------------------------- | --------------------------- | -------------- |
| `GET`  | `/api/v1/audit/logs`            | Query audit logs            | `audit:read`   |
| `POST` | `/api/v1/audit/logs/:id/verify` | Verify single log integrity | `audit:read`   |

**Query parameters (GET /audit/logs):**

| Parameter      | Type       | Description                 |
| -------------- | ---------- | --------------------------- |
| `sessionId`    | `string`   | Filter by session ID        |
| `agentDid`     | `string`   | Filter by Agent DID         |
| `credentialId` | `string`   | Filter by credential ID     |
| `from`         | `ISO 8601` | Start time                  |
| `to`           | `ISO 8601` | End time                    |
| `limit`        | `number`   | Items per page (default 50) |
| `offset`       | `number`   | Pagination offset           |

**Verify log response example:**

```json
{
  "auditId": "log-uuid",
  "signatureValid": true,
  "chainHashValid": true,
  "merklePathValid": true
}
```

### System

| Method | Path                         | Description                            |
| ------ | ---------------------------- | -------------------------------------- |
| `GET`  | `/health`                    | Service health check                   |
| `GET`  | `/api/v1/attestation/report` | Get TEE DCAP remote attestation report |

## Error Codes

All error responses follow this format:

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "Token does not have required scope: credential:decrypt"
  }
}
```

| HTTP Status | Error Code           | Description                           |
| ----------- | -------------------- | ------------------------------------- |
| 400         | `invalid_request`    | Request parameters invalid or missing |
| 401         | `unauthorized`       | Token missing or malformed            |
| 401         | `token_expired`      | Token expired, please regenerate      |
| 401         | `token_revoked`      | Token revoked                         |
| 403         | `insufficient_scope` | Token missing required Scope          |
| 404         | `not_found`          | Specified resource not found          |
| 422         | `credential_expired` | Credential expired                    |
| 500         | `internal_error`     | Server internal error                 |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toani.ai/toani-vault/getting-started/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.