> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Lists a page of tenants

`POST /api/web/v4/tenantspaged`

Returns tenants for the provided search parameters. Caller requires the TENANTS:VIEW permission. The following searchByAttributes are supported: <ul><li>hostname: a String up to 100 characters. Allowed operators are: EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH.</li><li>companyName: a String up to 100 characters. Allowed operators are: EQUALS, NOT_EQUALS, CONTAINS, NOT_CONTAINS, STARTS_WITH, ENDS_WITH.</li><li>contractMode: PRODUCTION, TRIAL, UNKNOWN. Allowed operator: EQUALS.</li><li>locked: true or false. Allowed operator: EQUALS. </li><li>serviceProvider: true or false. Allowed operator: EQUALS. </li><li>authenticationAccount: true or false. Allowed operator: EQUALS. </li><li>issuanceAccount: true or false. Allowed operator: EQUALS. </li><li>spIdp: true or false. Allowed operator: EQUALS. </li></ul>The orderByAttribute supports these attribute names: hostname, companyName, contractMode, locked, serviceProvider, authenticationAccount, issuanceAccount, spIdp.

## Request Body

Required.

### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "attributes": {
      "type": "array",
      "description": "Users search only: additional, non-core attributes to include in the returned object. Attribute names are specific to the returned object.",
      "items": {
        "type": "string",
        "description": "Users search only: additional, non-core attributes to include in the returned object. Attribute names are specific to the returned object."
      }
    },
    "cursor": {
      "type": "string",
      "description": "Identifies the page to return when paging over a result set--if present, search by / order by attributes are ignored."
    },
    "limit": {
      "maximum": 100,
      "minimum": 1,
      "type": "integer",
      "description": "Identifies the maximum number of items to include in a page (1-100).",
      "format": "int32"
    },
    "orderByAttribute": {
      "required": [
        "ascending",
        "name"
      ],
      "type": "object",
      "properties": {
        "ascending": {
          "type": "boolean",
          "description": "Identifies whether to order results in ascending order."
        },
        "name": {
          "type": "string",
          "description": "Identifies the attribute."
        }
      },
      "description": "An attribute used to sort the result from a search.",
      "title": "OrderByAttribute"
    },
    "searchByAttributes": {
      "type": "array",
      "description": "Identifies attributes for searching purposes. Some end-points have pre-defined values and ignore this attribute.",
      "items": {
        "required": [
          "name",
          "operator"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Identifies the attribute we are searching for."
          },
          "operator": {
            "type": "string",
            "description": "Identifies the operator.",
            "enum": [
              "EQUALS",
              "NOT_EQUALS",
              "CONTAINS",
              "NOT_CONTAINS",
              "STARTS_WITH",
              "ENDS_WITH",
              "GREATER_THAN",
              "GREATER_THAN_OR_EQUAL",
              "LESS_THAN",
              "LESS_THAN_OR_EQUAL",
              "IN",
              "EXISTS",
              "NOT_EXISTS"
            ]
          },
          "value": {
            "type": "string",
            "description": "Identifies the value of the attribute we are searching for."
          }
        },
        "description": "An attribute used during paging and/or searching.",
        "title": "SearchByAttribute"
      }
    }
  },
  "description": "Parameters specifying search attributes or a cursor to get results from a previous search.",
  "title": "SearchParms"
}
```

## Responses

### 200

Successful

#### application/json

Schema

```json
{
  "required": [
    "results"
  ],
  "type": "object",
  "properties": {
    "paging": {
      "required": [
        "limit"
      ],
      "type": "object",
      "properties": {
        "limit": {
          "maximum": 100,
          "minimum": 1,
          "type": "integer",
          "description": "The page limit used (1-100)",
          "format": "int32"
        },
        "nextCursor": {
          "type": "string",
          "description": "The cursor pointing to the next page."
        },
        "prevCursor": {
          "type": "string",
          "description": "The cursor pointing to the previous page."
        }
      },
      "description": "Contains navigation information.",
      "title": "Paging"
    },
    "results": {
      "type": "array",
      "description": "A single page with the list of tenants found.",
      "items": {
        "required": [
          "authenticationAccount",
          "companyName",
          "hostname",
          "id",
          "issuanceAccount",
          "locked",
          "serviceProvider",
          "spIdp"
        ],
        "type": "object",
        "properties": {
          "authenticationAccount": {
            "type": "boolean",
            "description": "A flag indicating if this tenant is an authentication account."
          },
          "companyName": {
            "type": "string",
            "description": "The name of the company that owns this tenant.",
            "example": "MyCompany Corp."
          },
          "contractMode": {
            "type": "string",
            "description": "The contract mode of a tenant, allowable values = 'PRODUCTION', 'TRIAL', example='TRIAL'.",
            "enum": [
              "PRODUCTION",
              "TRIAL",
              "UNKNOWN"
            ]
          },
          "hostname": {
            "type": "string",
            "description": "The hostname of the tenant.",
            "example": "mycompany.us.trustedauth.com"
          },
          "id": {
            "type": "string",
            "description": "The UUID of this tenant within the service provider."
          },
          "issuanceAccount": {
            "type": "boolean",
            "description": "A flag indicating if this tenant is an issuance account."
          },
          "locked": {
            "type": "boolean",
            "description": "A flag indicating if this tenant has been locked."
          },
          "otpProviderId": {
            "type": "string",
            "description": "The ID of the preferred OTP provider associated with this tenant, if any. Only visible to root tenant."
          },
          "previousHostname": {
            "type": "string",
            "description": "The previous hostname of the tenant.",
            "example": "mycompany.us.trustedauth.com"
          },
          "serviceProvider": {
            "type": "boolean",
            "description": "A flag indicating if this child tenant is a service provider."
          },
          "spIdp": {
            "type": "boolean",
            "description": "A flag indicating if this tenant is enabled for tenant management authentication."
          }
        },
        "description": "Information returned about a tenant of a service provider.",
        "title": "Tenant"
      }
    }
  },
  "description": "Contains paging information and the results from a tenants search.",
  "title": "TenantsPage"
}
```

### 400

Bad Request

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 401

Access denied

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 403

Forbidden

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 404

Not Found

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

### 409

Conflict

#### application/json

Schema

```json
{
  "type": "object",
  "properties": {
    "errorCode": {
      "type": "string",
      "description": "Error Codes specific to cause of failure.",
      "example": "invalid_user_response"
    },
    "errorMessage": {
      "type": "string",
      "description": "Additional Error Message describing the error.",
      "example": "Application id cannot be null"
    },
    "parameters": {
      "type": "array",
      "description": "Optional additional error information.",
      "items": {
        "type": "object",
        "description": "Optional additional error information."
      }
    }
  },
  "description": "Object containing information about errors reported by services.",
  "title": "ErrorInfo"
}
```

## Security

Requirements

```json
[
  {
    "AdminAPIAuthentication": [
      "TENANTS:VIEW"
    ]
  }
]
```