{
  "openapi": "3.0.1",
  "info": {
    "title": "Users",
    "version": "v1.1"
  },
  "tags": [
    {
      "name": "Users"
    }
  ],
  "paths": {
    "/users": {
      "get": {
        "summary": "List users",
        "tags": [
          "Users"
        ],
        "description": "Retrieves a list of users with optional filtering and pagination",
        "operationId": "getUsers",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "per_page",
            "in": "query",
            "description": "Number of users to retrieve per page",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25,
              "example": 25
            },
            "required": false
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number to retrieve",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "example": 1
            },
            "required": false
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sort field and direction.  Can sort by: name, first_name, last_name, email, internal_user_id. Prefix with + for ascending or - for descending (defaults to ascending).",
            "schema": {
              "type": "string",
              "example": "+name"
            },
            "required": false
          }
        ],
        "responses": {
          "200": {
            "description": "Users retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/user"
                      }
                    },
                    "links": {
                      "$ref": "#/components/schemas/paginated_index_links"
                    },
                    "meta": {
                      "$ref": "#/components/schemas/paginated_index_meta"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://demo.snapdocsevault.com/api",
      "description": "Snapdocs Evault demo environment"
    },
    {
      "url": "https://www.snapdocsevault.com/api",
      "description": "Snapdocs Evault production environment"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "paginated_index_links": {
        "type": "object",
        "properties": {
          "self": {
            "type": "string",
            "example": "http://snapdocsevault.com/lender_preferences?page%5Bnumber%5D=1&page%5Bsize%5D=25",
            "description": "the current page"
          },
          "first": {
            "type": "string",
            "example": "http://snapdocsevault.com/lender_preferences?page%5Bnumber%5D=1&page%5Bsize%5D=25",
            "description": "the first page"
          },
          "prev": {
            "type": "string",
            "description": "the previous page"
          },
          "next": {
            "type": "string",
            "description": "the next page"
          },
          "last": {
            "type": "string",
            "description": "the last page"
          }
        },
        "description": "self descriptive link to access pagination"
      },
      "paginated_index_meta": {
        "type": "object",
        "description": "meta data for pagination",
        "properties": {
          "current_page": {
            "type": "integer",
            "example": 1,
            "description": "the current page"
          },
          "total_pages": {
            "type": "integer",
            "example": 2,
            "description": "the total number of pages"
          },
          "next_page": {
            "type": "integer",
            "example": 2,
            "description": "the next page"
          },
          "page_size": {
            "type": "integer",
            "example": 25,
            "description": "the number of items per page"
          },
          "total_count": {
            "type": "integer",
            "example": 35,
            "description": "the total number of items"
          }
        }
      },
      "user": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "5279e4ca-cd04-49b3-9863-d94e9acc35fe",
            "description": "The user id"
          },
          "type": {
            "type": "string",
            "example": "users",
            "description": "The type of object"
          },
          "attributes": {
            "type": "object",
            "properties": {
              "email": {
                "type": "string",
                "format": "email",
                "example": "user@example.com",
                "description": "User email address"
              },
              "first_name": {
                "type": "string",
                "example": "John",
                "description": "User first name"
              },
              "last_name": {
                "type": "string",
                "example": "Doe",
                "description": "User last name"
              },
              "name": {
                "type": "string",
                "example": "John Doe",
                "description": "User full name (computed from first and last name)"
              },
              "internal_user_id": {
                "type": "string",
                "example": "internal_123",
                "description": "Internal identifier for the user"
              },
              "disabled_at": {
                "type": "string",
                "format": "date-time",
                "example": "2023-07-25T20:06:17.903Z",
                "description": "Timestamp when user was disabled, null if active"
              },
              "last_sign_in_at": {
                "type": "string",
                "format": "date-time",
                "example": "2023-07-25T20:06:17.903Z",
                "description": "Timestamp when user the user last logged in, null if the user never logged in"
              },
              "customer_id": {
                "type": "string",
                "format": "uuid",
                "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "description": "Associated customer ID"
              },
              "role_id": {
                "type": "string",
                "format": "uuid",
                "example": "46f97b7e-8a32-4ca0-849c-85db4f92e9c7",
                "description": "User role ID"
              },
              "role_name": {
                "type": "string",
                "example": "Admin",
                "description": "Name of the user role"
              }
            }
          }
        }
      },
      "user_evault_access_link": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "12345678-1234-1234-1234-123456789012",
            "description": "Access link ID"
          },
          "evault_id": {
            "type": "string",
            "format": "uuid",
            "example": "e726f0ee-7c5b-441c-804c-0e91e9ab404a",
            "description": "Associated evault ID"
          },
          "role_id": {
            "type": "string",
            "format": "uuid",
            "example": "role123-1234-1234-1234-123456789012",
            "description": "Role ID for this evault access"
          },
          "active": {
            "type": "boolean",
            "example": true,
            "description": "Whether this access link is active"
          },
          "deactivated_at": {
            "type": "string",
            "format": "date-time",
            "example": null,
            "description": "Timestamp when access was deactivated, null if active"
          }
        }
      },
      "users": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/user"
            }
          },
          "links": {
            "$ref": "#/components/schemas/paginated_index_links"
          },
          "meta": {
            "$ref": "#/components/schemas/paginated_index_meta"
          }
        }
      }
    }
  }
}