{
  "openapi": "3.0.0",
  "info": {
    "title": "Paxos Identity Controls API",
    "version": "v2-preview"
  },
  "security": [
    {
      "OAuth2": ["identity:read_identity", "identity:write_identity"]
    }
  ],
  "paths": {
    "/v2/identity/controls": {
      "get": {
        "summary": "List Identity Controls",
        "description": "List identity controls associated with an identity.",
        "operationId": "ListIdentityControls",
        "responses": {
          "200": {
            "description": "A successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListIdentityControlsResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "parameters": [
          {
            "name": "identity_id",
            "description": "The Identity ID whose controls to retrieve.",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include_deleted",
            "description": "Include deleted controls in the response.",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "description": "Number of results to return. Defaults to 100 if no limit is provided. Maximum 1000.",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32"
            }
          },
          {
            "name": "page_cursor",
            "description": "Optional: Cursor for getting the next page of results.",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Identity Controls"
        ],
        "security": [
          {
            "OAuth2": [
              "identity:read_identity_control"
            ]
          }
        ]
      },
      "post": {
        "summary": "Create Identity Control",
        "description": "Create a new identity control on an identity.",
        "operationId": "CreateIdentityControl",
        "responses": {
          "200": {
            "description": "A successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IdentityControl"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateIdentityControlRequest"
              }
            }
          },
          "required": true
        },
        "tags": [
          "Identity Controls"
        ],
        "security": [
          {
            "OAuth2": [
              "identity:write_identity_control"
            ]
          }
        ]
      },
      "delete": {
        "summary": "Delete Identity Control",
        "description": "Delete an identity control on an identity.",
        "operationId": "DeleteIdentityControl",
        "responses": {
          "200": {
            "description": "A successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteIdentityControlResponse"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "control_id",
            "description": "The control ID to be deleted.",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "reason",
            "description": "Reason for deleting the identity control.",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "tags": [
          "Identity Controls"
        ],
        "security": [
          {
            "OAuth2": [
              "identity:write_identity_control"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://oauth.paxos.com/oauth2/token",
            "scopes": {
              "identity:read_identity": "Read identity data",
              "identity:write_identity": "Create and manage identities"
            }
          }
        }
      }
    },
    "schemas": {
      "IdentityControl": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for this control"
          },
          "type": {
            "$ref": "#/components/schemas/IdentityControlType"
          },
          "set_by": {
            "$ref": "#/components/schemas/IdentityControlSetBy"
          },
          "is_overridable": {
            "type": "boolean",
            "description": "Whether this control can be deleted by the client application"
          },
          "reason_code": {
            "$ref": "#/components/schemas/IdentityControlReasonCode"
          },
          "reason": {
            "type": "string",
            "description": "Freetext reason why this identity control was set"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Time this identity control was created"
          },
          "deleted_at": {
            "type": "string",
            "format": "date-time",
            "description": "Time this identity control was deleted"
          }
        }
      },
      "IdentityControlReasonCode": {
        "type": "string",
        "enum": [
          "OTHER",
          "END_USER_REQUEST",
          "INACTIVITY",
          "COMPLIANCE_KYC",
          "COMPLIANCE_EDD",
          "COMPLIANCE_SCREENING",
          "COMPLIANCE_INVESTIGATION",
          "ONBOARDING_INCOMPLETE",
          "RISK_FRAUD",
          "LEGAL_ORDER",
          "ADMINISTRATIVE"
        ],
        "description": "Reason code for why a control was applied.\n\n- `OTHER`: Miscellaneous reason not captured by existing categories\n- `END_USER_REQUEST`: Control applied at the end user's request\n- `INACTIVITY`: Control applied due to prolonged inactivity in accordance with dormancy or lifecycle management policies\n- `COMPLIANCE_KYC`: Control applied due to unmet KYC requirements, including missing, expired, failed, or unresponsiveness to refresh obligations\n- `COMPLIANCE_EDD`: Control applied due to Enhanced Due Diligence (EDD) requirements, including failure to complete EDD reviews, provide requested information, or satisfy heightened risk assessment criteria\n- `COMPLIANCE_SCREENING`: Control applied as a result of sanctions, politically exposed person (PEP), or adverse media screening hits\n- `COMPLIANCE_INVESTIGATION`: Control applied while an identity is under active compliance, risk, or regulatory investigation, including reviews triggered by monitoring alerts or external inquiries\n- `ONBOARDING_INCOMPLETE`: Control applied because the onboarding process was not successfully completed, including failure to respond to requests for information or provide required documentation\n- `RISK_FRAUD`: Control applied due to suspected or confirmed fraud, abuse, or security risk, including account compromise, transaction fraud, or policy violations\n- `LEGAL_ORDER`: Control applied to comply with a legal, regulatory, or law-enforcement directive, including court orders, asset preservation requests, or regulatory instructions\n- `ADMINISTRATIVE`: Control applied for operational or platform-initiated reasons not attributable to the end user or compliance failure, such as system remediation or account restructuring"
      },
      "IdentityControlSetBy": {
        "type": "string",
        "enum": [
          "SET_BY_PAXOS",
          "SET_BY_CLIENT"
        ],
        "description": "Indicates who set the control."
      },
      "IdentityControlType": {
        "type": "string",
        "enum": [
          "SELL_ONLY",
          "CLOSED",
          "FROZEN",
          "DORMANT"
        ],
        "description": "The type of control applied to an identity.\n\n- `SELL_ONLY`: Identity may only sell\n- `CLOSED`: Identity is closed and cannot perform any actions\n- `FROZEN`: Identity is frozen due to compliance reasons\n- `DORMANT`: Identity is dormant due to inactivity"
      },
      "CreateIdentityControlRequestClientIdentityControlType": {
        "type": "string",
        "enum": [
          "SELL_ONLY",
          "CLOSED",
          "DORMANT"
        ],
        "description": "The type of control applied to an identity.\n\n- `SELL_ONLY`: Identity may only sell\n- `CLOSED`: Identity is closed and cannot perform any actions\n- `DORMANT`: Identity is dormant due to inactivity"
      },
      "CreateIdentityControlRequest": {
        "type": "object",
        "properties": {
          "identity_id": {
            "type": "string",
            "description": "The Identity ID"
          },
          "type": {
            "$ref": "#/components/schemas/CreateIdentityControlRequestClientIdentityControlType"
          },
          "reason_code": {
            "$ref": "#/components/schemas/IdentityControlReasonCode"
          },
          "reason": {
            "type": "string",
            "description": "Freetext reason for setting the control"
          }
        },
        "required": [
          "identity_id",
          "type",
          "reason_code"
        ]
      },
      "ListIdentityControlsResponse": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/IdentityControl"
            },
            "description": "The list of identity controls."
          },
          "next_page_cursor": {
            "type": "string",
            "description": "Cursor token for fetching the next page. Empty if there are no more pages."
          }
        }
      },
      "DeleteIdentityControlResponse": {
        "type": "object"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad Request",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/examples/Problem_bad_request"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorized",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/examples/Problem_unauthorized"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/examples/Problem_forbidden"
            }
          }
        }
      },
      "NotFound": {
        "description": "Not Found",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/examples/Problem_not_found"
            }
          }
        }
      }
    },
    "examples": {
      "Problem_bad_request": {
        "value": {
          "type": "about:blank",
          "title": "Bad Request",
          "status": 400,
          "detail": "Invalid request format or missing required fields"
        }
      },
      "Problem_unauthorized": {
        "value": {
          "type": "about:blank",
          "title": "Unauthorized",
          "status": 401,
          "detail": "no authorization header set"
        }
      },
      "Problem_forbidden": {
        "value": {
          "type": "about:blank",
          "title": "Forbidden",
          "status": 403,
          "detail": "user account is disabled"
        }
      },
      "Problem_not_found": {
        "value": {
          "type": "about:blank",
          "title": "Not Found",
          "status": 404,
          "detail": "identity not found"
        }
      }
    }
  }
}