Fetch Tenants

post

https://{application_vanity_domain}/api/v1/tenant-discovery/fetch-tenants

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Fetches all distinct tenants that a user is associated with within an application that satisfy the following criteria:

The tenant must contain a user whose email matches the specified email in the tenant discovery request.
The user's email must be verified.
The user must have an ACTIVE status
The tenant must have an ACTIVE status.
The tenant type must not be equal to GLOBAL.

Note, this API can be called in three distinct ways.

The first way is directly. With this approach, the applicationId and email fields must be provided in the request body. Optionally, a clientId can be provided to utilize the login URL from the client when resolving the login URLs returned in the response.
The second way is from a tenant discovery email flow. With this approach, the emailAuthCode field must be provided in the request body. The results returned in the response will be based on the applicationId and email fields that were specified when the tenant discovery email was sent.
The third way is from a tenant discovery OTP email flow. With this approach, the requestCode and verificationCode fields must be provided in the request body. The results returned in the response will be based on the applicationId and email fields that were specified when the tenant discovery OTP email was sent.

This API utilizes cursor pagination with the results being sorted by tenantDomainName in ascending order.

Required Permissions

Below is the list of required permissions needed to interact with this API. For each permission, the allowed permission boundaries are also specified.

Permission	Boundary	Description
tenant-discovery-workflow:execute	Application	The subject can perform this operation for requests associated with the application to which the subject belongs.

Query Params

count

number

1 to 50

Defaults to 20

The maximum number of results that can be returned in a query response.

page_before

string

Cursor that will be used to retrieve the previous page of results. Note, the page_before and page_after query parameters can't both be used in the same request.

page_after

string

Cursor that will be used to retrieve the next page of results. Note, the page_before and page_after query parameters can't both be used in the same request.

resolve_email_domain_mappings

boolean

Defaults to false

If this value is set to true, then active tenants that have a discovery email domain equal to the domain of the email specified in the discovery request will be returned in the results.

Body Params

Fetch Tenants Request JSON object

Object representing a request to fetch all tenants that a user belongs to.

emailAuthCode

string

length ≥ 1

The email auth code that will be used to authorize the request. If provided then all other request fields must be null.

applicationId

string

length between 1 and 26

The ID of the application that the fetch tenants request will be scoped to, only tenants belonging to this application will be returned. If provided then all other request fields must be null except for email and clientId.

string

length between 1 and 200

The email of the user whose tenants should be retrieved. Tenants that have an active user with a verified email matching this email will be returned in the results. If provided then all other request fields must be null except for applicationId and clientId.

clientId

string

length between 1 and 26

Optional ID of the client that initiated the request. If the client has a login URL defined it will be used to resolve the login URL returned in the response instead of the application login URL. If provided then all other request fields must be null except for applicationId and email.

requestCode

string

length ≥ 1

A code that is used to identify the current tenant discovery request. If provided then all other request fields must be null except for verificationCode.

verificationCode

string

length ≥ 1

The verification code that was sent to the user's email. If provided then all other request fields must be null except for requestCode.

Responses

Required Permissions

200OK

400Bad Request

401Unauthorized

403Forbidden

405Method Not Allowed

406Not Acceptable

500Internal Server Error

503Service Unavailable