Add Identity Requirements and Dormancy Lifecycle Documentation

api-reference/preview/identity-dormancy-lifecycle.mdx

@@ -0,0 +1,273 @@
+---
+title: 'Dormancy Lifecycle'
+description: Manage dormant identities with automated lifecycle controls.
+---
+
+## Overview
+
+The Identity Dormancy Lifecycle feature enables you to manage identities that become inactive over time. Use Identity Controls to mark identities as dormant and the enhanced Identity API to monitor their status.
+
+**Key capabilities:**
+- Query identities with detailed status information including pending requirements, failed requirements, and active controls
+- Set and remove dormant controls on identities
+- Filter identities by active control type and reason code
+- Track control lifecycle with creation and deletion timestamps
+
+## Use Cases
+
+- **Compliance**: Automatically flag accounts inactive for regulatory periods (e.g., 90, 180, or 365 days)
+- **Risk management**: Reduce exposure by restricting dormant account activity
+- **Resource optimization**: Identify and manage inactive identities
+- **Reactivation workflows**: Track and restore dormant accounts when users return
+
+## Understanding Dormancy Controls
+
+A dormancy control marks an identity as inactive, changing its status to `DISABLED`. This prevents the identity from performing operations while maintaining a complete audit trail of the control lifecycle.
+
+### Control Types
+
+| Type | Description | Set By |
+|------|-------------|--------|
+| `DORMANT` | Identity is dormant due to inactivity | Client or Paxos |
+| `CLOSED` | Identity is permanently closed | Client or Paxos |
+
+### Reason Codes
+
+| Code | Description | Typical Use |
+|------|-------------|-------------|
+| `DORMANT` | Identity inactive for specified period | Automated dormancy workflows |
+| `END_USER_REQUESTED` | User requested the control | Manual account closure |
+| `COMPLIANCE` | Regulatory or compliance requirement | Paxos-initiated controls |
+| `OTHER` | Miscellaneous reason | Custom scenarios |
+
+### Identity Status Impact
+
+When a dormant control is active, the identity status changes to `DISABLED`. The `status_details` field shows the active control:
+
+```json
+{
+  "id": "f190b163-208f-4d73-8deb-4fb8b24add00",
+  "status": "DISABLED",
+  "status_details": {
+    "active_controls": [
+      {
+        "id": "59b8e3c5-2b6e-4fa6-afcf-8c685598241d",
+        "type": "DORMANT",
+        "controlled_by": "CLIENT",
+        "reason_code": "DORMANT",
+        "reason": "No activity for 180 days",
+        "created_at": "2006-01-02T15:04:05Z"
+      }
+    ]
+  }
+}
+```
+
+## Workflow
+
+### ➊ Set Dormant Control
+
+Mark an identity as dormant using the Create Identity Control endpoint.
+
+```bash
+curl -X POST "https://api.paxos.com/v2/identity/controls" \
+  -H "Authorization: Bearer {access_token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "identity_id": "f190b163-208f-4d73-8deb-4fb8b24add00",
+    "type": "DORMANT",
+    "reason_code": "DORMANT",
+    "reason": "No activity for 180 days"
+  }'
+```
+
+The identity's status immediately changes to `DISABLED` and operations are blocked.
+
+### �② List Dormant Identities
+
+Query all identities with dormant controls using the enhanced List Identities endpoint.
+
+**Filter by dormant control type:**
+
+```bash
+curl -X GET "https://api.paxos.com/identity/identities?control_type=DORMANT" \
+  -H "Authorization: Bearer {access_token}"
+```
+
+**Filter by reason code:**
+
+```bash
+curl -X GET "https://api.paxos.com/identity/identities?control_reason_code=DORMANT" \
+  -H "Authorization: Bearer {access_token}"
+```
+
+**Filter by status:**
+
+```bash
+curl -X GET "https://api.paxos.com/identity/identities?status=DISABLED" \
+  -H "Authorization: Bearer {access_token}"
+```
+
+### ➌ Check Identity Details
+
+Retrieve a specific identity to view its complete status including active controls, pending requirements, and failed requirements.
+
+```bash
+curl -X GET "https://api.paxos.com/identity/identities/{identity_id}" \
+  -H "Authorization: Bearer {access_token}"
+```
+
+### ➍ View Control History
+
+List all controls (active and deleted) for an identity to maintain a complete audit trail.
+
+```bash
+curl -X GET "https://api.paxos.com/v2/identity/controls?identity_id={identity_id}&include_deleted=true" \
+  -H "Authorization: Bearer {access_token}"
+```
+
+**Response:**
+
+```json
+{
+  "items": [
+    {
+      "id": "ae54b3b4-cce6-4707-b34b-c9c4f0537798",
+      "type": "DORMANT",
+      "controlled_by": "CLIENT",
+      "reason_code": "DORMANT",
+      "reason": "No activity for 180 days",
+      "created_at": "2006-01-02T15:04:05Z"
+    }
+  ],
+  "next_page_cursor": ""
+}
+```
+
+### ➎ Remove Dormant Control
+
+Reactivate a dormant identity by deleting the control.
+
+```bash
+curl -X DELETE "https://api.paxos.com/v2/identity/controls" \
+  -H "Authorization: Bearer {access_token}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "identity_id": "f190b163-208f-4d73-8deb-4fb8b24add00",
+    "id": "ae54b3b4-cce6-4707-b34b-c9c4f0537798",
+    "reason": "User returned and requested reactivation"
+  }'
+```
+
+The identity's status returns to its previous state (typically `APPROVED` if no other controls or requirements apply).
+
+## Status Details Structure
+
+The `status_details` field provides comprehensive information about an identity's current state:
+
+**Active Controls** - Controls currently applied to the identity
+
+```json
+{
+  "active_controls": [
+    {
+      "id": "control-id",
+      "type": "DORMANT",
+      "controlled_by": "CLIENT",
+      "reason_code": "DORMANT",
+      "reason": "Descriptive reason",
+      "created_at": "2006-01-02T15:04:05Z"
+    }
+  ]
+}
+```
+
+**Pending Requirements** - Requirements that must be satisfied before the identity can be approved
+
+```json
+{
+  "pending_requirements": [
+    {
+      "type": "SANCTIONS_SCREENING",
+      "message": "Pending Sanctions Screening"
+    }
+  ]
+}
+```
+
+**Failed Requirements** - Requirements that failed and prevent identity approval
+
+```json
+{
+  "failed_requirements": [
+    {
+      "type": "RISK_RATING",
+      "message": "Jurisdiction not supported by Paxos"
+    }
+  ]
+}
+```
+
+## Best Practices
+
+### Automated Dormancy Detection
+
+Implement a scheduled job to detect and flag dormant identities:
+
+1. Query identities last active before your threshold (e.g., 180 days ago)
+2. Filter out identities that already have a dormant control
+3. Create dormant controls for qualifying identities
+4. Log all dormancy actions for audit trails
+
+### Reactivation Workflow
+
+When a dormant user returns:
+
+1. Verify user identity through your authentication flow
+2. List the identity's controls to find the dormant control ID
+3. Delete the dormant control with a descriptive reason
+4. Check the identity status to confirm it's no longer `DISABLED`
+5. Allow user to resume normal operations
+
+### Pagination
+
+When querying large identity sets, use pagination:
+
+```bash
+# Initial request
+curl -X GET "https://api.paxos.com/identity/identities?limit=100" \
+  -H "Authorization: Bearer {access_token}"
+
+# Subsequent pages
+curl -X GET "https://api.paxos.com/identity/identities?limit=100&page_cursor={next_page_cursor}" \
+  -H "Authorization: Bearer {access_token}"
+```
+
+### Control History
+
+Keep `include_deleted=true` when listing controls to maintain a complete audit trail of an identity's lifecycle.
+
+## Identity Status States
+
+| Status | Description |
+|--------|-------------|
+| `PENDING` | Identity verification in progress |
+| `APPROVED` | Identity approved and active |
+| `DENIED` | Identity denied due to failed requirements |
+| `DISABLED` | Identity disabled (e.g., by dormant or closed control) |
+| `ERROR` | Error during identity processing |
+
+## API Reference
+
+### Identity Queries
+- [List Identities](/api-reference/preview/list-identities) - Query identities with filtering
+- [Get Identity](/api-reference/preview/get-identity) - Retrieve detailed identity status
+
+### Identity Controls
+- [List Identity Controls](/api-reference/preview/list-identity-controls) - View all controls for an identity
+- [Create Identity Control](/api-reference/preview/create-identity-control) - Set a new control
+- [Delete Identity Control](/api-reference/preview/delete-identity-control) - Remove an existing control
+
+## Support
+
+> Questions? Contact [Support](https://support.paxos.com).

api-reference/preview/identity-requirements-overview.mdx

@@ -0,0 +1,24 @@
+---
+title: 'Overview'
+description: Understanding identity requirements and status details.
+---
+
+## Overview
+
+🚧 **Work in Progress** - This documentation is under active development.
+
+The Identity Requirements API provides detailed visibility into the requirements that govern identity approval and status changes.
+
+## Coming Soon
+
+- Comprehensive guide to identity requirements
+- Requirement types and their meanings
+- Status progression and state transitions
+- Best practices for handling requirements
+- Integration patterns and workflows
+
+## Available Now
+
+Explore the Identity Dormancy Lifecycle guide to get started with identity controls and status monitoring.
+
+> Questions? Contact [Support](https://support.paxos.com).

api-reference/preview/identity-requirements/get-identity.mdx

@@ -0,0 +1,7 @@
+---
+openapi: get /identity/identities/{id}
+---
+
+```bash OAuth Scope
+identity:read_identity
+```

api-reference/preview/identity-requirements/list-identities.mdx

@@ -0,0 +1,7 @@
+---
+openapi: get /identity/identities
+---
+
+```bash OAuth Scope
+identity:read_identity
+```