# listPartnerTenants

Source: /openapi/thomas-federated.openapi.json

## Operation

| Method | URL |
|---|---|
| GET | https://api.thomas.co/v1/tenants |

| Field | Value |
|---|---|
| operationId | listPartnerTenants |
| method | GET |
| server | https://api.thomas.co |
| path | /v1/tenants |
| tags | `Partner Tenants` |
| summary | List the tenants this API client holds a grant on |
| badges | None |
| scopes | None |

## Description

Returns one row per tenant on which the calling API client holds a grant that is `active`, `pending` or `inactive`, with the tenant id to send as `Thomas-Tenant-Id`, the tenant's name, and this client's own grant status, partner role and scopes. Revoked and rejected grants are not listed, and nothing about any other API client or partner is. Ordered by `tenantId` ascending and paged by cursor; `nextCursor` is null on the last page.

## Request Parameters

| Name | In | Required | Schema | Description |
|---|---|---|---|---|
| limit | query | false | integer | Narrow the page. Defaults to 25, which is also the maximum. |
| cursor | query | false | string | The `nextCursor` from a previous page. Omit for the first page. |

## Request Body

None.

## Responses

| Status | Description | Schema refs |
|---|---|---|
| 200 | One bounded page of tenants | #/components/schemas/PartnerTenantListResponseDto |
| 400 | The paging parameters were not valid, or a tenant selector was sent | #/components/schemas/ApiErrorResponseDto |
| 401 | Invalid or missing authentication token (AUTH_TOKEN_INVALID) | #/components/schemas/ApiErrorResponseDto |
| 403 | Only a provisioned Partner-owned API client may call this operation | #/components/schemas/ApiErrorResponseDto |
| 429 | Rate limit exceeded. | #/components/schemas/ApiErrorResponseDto |

### Response 429 headers

| Name | Description | Schema |
|---|---|---|
| Retry-After | Seconds until the rate-limit block expires before retrying. | {"type":"integer","minimum":0} |
| RateLimit-Limit | Configured request limit for the active rate-limit window. | {"type":"integer"} |
| RateLimit-Remaining | Requests remaining in the active rate-limit window; zero when blocked. | {"type":"integer"} |
| RateLimit-Reset | Seconds until the rate-limit block expires. | {"type":"integer","minimum":0} |

## Artifact Examples

### Response 400 example — LIST_CURSOR_INVALID

```json
{
  "statusCode": 400,
  "message": "Invalid cursor",
  "error": "LIST_CURSOR_INVALID"
}
```

### Response 400 example — AUTH_TENANT_CONTEXT_INVALID

```json
{
  "statusCode": 400,
  "message": "This operation does not accept a Thomas-Tenant-Id header",
  "error": "AUTH_TENANT_CONTEXT_INVALID"
}
```

### Response 401 example

```json
{
  "statusCode": 401,
  "message": "Invalid or missing authentication token",
  "error": "AUTH_TOKEN_INVALID"
}
```

### Response 403 example — PRINCIPAL_TYPE_NOT_ALLOWED (The API client is not a provisioned Partner-owned client)

```json
{
  "statusCode": 403,
  "message": "API client is not permitted to call this operation",
  "error": "PRINCIPAL_TYPE_NOT_ALLOWED"
}
```

### Response 403 example — PRINCIPAL_TYPE_NOT_ALLOWED (A Thomas-On-Behalf-Of header was sent)

```json
{
  "statusCode": 403,
  "message": "On-behalf access is not permitted for this operation",
  "error": "PRINCIPAL_TYPE_NOT_ALLOWED"
}
```

### Response 403 example — PRINCIPAL_TYPE_NOT_ALLOWED (The caller is a person or a service account)

```json
{
  "statusCode": 403,
  "message": "This principal is not permitted to call this operation",
  "error": "PRINCIPAL_TYPE_NOT_ALLOWED"
}
```

### Response 429 example

```json
{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests",
  "error": "HTTP_TOO_MANY_REQUESTS"
}
```