> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Organizations
> Search Organizations using the Stytch B2B API.
export const organization = "Represents an instance or tenant in your application, typically mapping to each of your top-level customers.";
Searches across Organizations and returns an array of [Organization](/api-reference/b2b/api/organizations/organization-object) objects.
If no body parameters are provided, the response includes all organizations with no filtering applied. All fuzzy search filters require a minimum of three characters.
This endpoint is not recommended for use in login flows. Scaling issues may occur, as search performance may vary from \~150 milliseconds to 9 seconds depending on query complexity and rate limits are set to 100 requests/second.
## Filter Reference
Each query operand requires a `filter_name` and `filter_value`. The table below shows all available filters, their value types, and descriptions.
| Filter Name | Value Type | Description | Example |
| --------------------------- | --------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `organization_ids` | `array[string]` | Filter by one or more exact organization IDs. | `["organization-test-16d9ba61-97a1-4ba4-9720-b03761dc50c6"]` |
| `organization_slugs` | `array[string]` | Filter by one or more exact organization slugs. | `["acme-corp"]` |
| `organization_slug_fuzzy` | `string` | Fuzzy search for organization by slug. Requires a minimum of three characters. | `"acme"` |
| `organization_name_fuzzy` | `string` | Fuzzy search for organization by name. Requires a minimum of three characters. | `"Acme"` |
| `member_emails` | `array[string]` | Filter by one or more exact member email addresses. | `["member@example.com"]` |
| `member_email_fuzzy` | `string` | Fuzzy search for organization by member email address. Requires a minimum of three characters. | `"john"` |
| `allowed_domains` | `array[string]` | Filter by one or more exact allowed email domains. | `["example.com"]` |
| `allowed_domain_fuzzy` | `string` | Fuzzy search for organization by allowed email domain. Requires a minimum of three characters. | `"exam"` |
| `claimed_email_domains` | `array[string]` | Filter by one or more exact claimed email domains. | `["acme.com"]` |
| `has_active_sso_connection` | `boolean` | Filter organizations by whether they have an active SSO connection (SAML, OIDC, or external). | `true` |
| `sso_connection_id` | `string` | Filter by exact SSO connection ID (SAML, OIDC, or external). | `"saml-connection-test-1234567890"` |
## OpenAPI
````yaml POST /v1/b2b/organizations/search
openapi: 3.0.3
info:
title: Stytch API
description: The Stytch API provides endpoints for authentication and user management.
version: 2.1.1
contact:
name: Stytch Support
url: https://stytch.com/docs
email: support@stytch.com
servers:
- url: https://api.stytch.com
description: Production server
- url: https://test.stytch.com
description: Test server
security:
- basicAuth: []
paths:
/v1/b2b/organizations/search:
post:
tags:
- Organization
summary: Search
description: >-
**Warning**: This endpoint is not recommended for use in login flows.
Scaling issues may occur, as search performance may vary from ~150
milliseconds to 9 seconds depending on query complexity and rate limits
are set to 100 requests/minute.
Search across your Organizations. Returns an array of Organization
objects.
operationId: api_organization_v1_Search
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/api_organization_v1_SearchRequest'
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/api_organization_v1_SearchResponse'
'400':
description: Bad request
'401':
description: Unauthorized
content:
application/json:
example:
status_code: 401
request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
error_type: unauthorized_credentials
error_message: Unauthorized credentials.
error_url: https://stytch.com/docs/api/errors/401
'429':
description: Too Many Requests
content:
application/json:
example:
status_code: 429
request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
error_type: too_many_requests
error_message: Too many requests have been made.
error_url: https://stytch.com/docs/api/errors/429
'500':
description: Internal server error
content:
application/json:
example:
status_code: 500
request_id: request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141
error_type: internal_server_error
error_message: >-
Oops, something seems to have gone wrong, please reach out to
support@stytch.com to let us know what went wrong.
error_url: https://stytch.com/docs/api/errors/500
components:
schemas:
api_organization_v1_SearchRequest:
type: object
properties:
cursor:
type: string
description: >-
The `cursor` field allows you to paginate through your results. Each
result array is limited to 1000 results. If your query returns more
than 1000 results, you will need to paginate the responses using the
`cursor`. If you receive a response that includes a non-null
`next_cursor` in the `results_metadata` object, repeat the search
call with the `next_cursor` value set to the `cursor` field to
retrieve the next page of results. Continue to make search calls
until the `next_cursor` in the response is null.
limit:
type: integer
format: int32
minimum: 0
description: >-
The number of search results to return per page. The default limit
is 100. A maximum of 1000 results can be returned by a single search
request. If the total size of your result set is greater than one
page size, you must paginate the response. See the `cursor` field.
query:
$ref: '#/components/schemas/api_organization_v1_SearchQuery'
description: >-
The optional query object contains the operator, i.e. `AND` or `OR`,
and the operands that will filter your results. Only an operator is
required. If you include no operands, no filtering will be applied.
If you include no query object, it will return all Organizations
with no filtering applied.
description: Request type
api_organization_v1_SearchResponse:
type: object
properties:
request_id:
type: string
description: >-
Globally unique UUID that is returned with every API call. This
value is important to log for debugging purposes; we may ask for
this value to help identify a specific API call when helping you
debug an issue.
organizations:
type: array
items:
$ref: '#/components/schemas/api_organization_v1_Organization'
description: >-
An array of [Organization
objects](https://stytch.com/docs/b2b/api/organization-object).
results_metadata:
$ref: '#/components/schemas/api_organization_v1_ResultsMetadata'
description: >-
The search `results_metadata` object contains metadata relevant to
your specific query like `total` and `next_cursor`.
status_code:
type: integer
format: int32
description: >-
The HTTP status code of the response. Stytch follows standard HTTP
response status code patterns, e.g. 2XX values equate to success,
3XX values are redirects, 4XX are client errors, and 5XX are server
errors.
required:
- request_id
- organizations
- results_metadata
- status_code
api_organization_v1_SearchQuery:
type: object
properties:
operator:
$ref: >-
#/components/schemas/api_organization_v1_organizations_SearchQueryOperator
description: |-
The action to perform on the operands. The accepted values are:
`AND` – all the operand values provided must match.
`OR` – **[DEPRECATED]** the operator will return any matches to at least one of the operand values you supply. This parameter is retained for legacy use cases only and is no longer supported. We strongly recommend breaking down complex queries into multiple search queries instead.
operands:
type: array
items:
type: object
additionalProperties: true
description: >-
An array of operand objects that contains all of the filters and
values to apply to your search query.
required:
- operator
- operands
api_organization_v1_Organization:
type: object
properties:
organization_id:
type: string
description: >-
Globally unique UUID that identifies a specific Organization. The
`organization_id` is critical to perform operations on an
Organization, so be sure to preserve this value. You may also use
the organization_slug or organization_external_id here as a
convenience.
organization_name:
type: string
description: >-
The name of the Organization. Must be between 1 and 128 characters
in length.
organization_logo_url:
type: string
description: The image URL of the Organization logo.
organization_slug:
type: string
description: >-
The unique URL slug of the Organization. The slug only accepts
alphanumeric characters and the following reserved characters: `-`
`.` `_` `~`. Must be between 2 and 128 characters in length.
Wherever an organization_id is expected in a path or request
parameter, you may also use the organization_slug as a convenience.
sso_jit_provisioning:
type: string
description: >-
The authentication setting that controls the JIT provisioning of
Members when authenticating via SSO. The accepted values are:
`ALL_ALLOWED` – the default setting, new Members will be automatically provisioned upon successful authentication via any of the Organization's `sso_active_connections`.
`RESTRICTED` – only new Members with SSO logins that comply with `sso_jit_provisioning_allowed_connections` can be provisioned upon authentication.
`NOT_ALLOWED` – disable JIT provisioning via SSO.
sso_jit_provisioning_allowed_connections:
type: array
items:
type: string
description: >-
An array of `connection_id`s that reference [SAML Connection
objects](https://stytch.com/docs/b2b/api/saml-connection-object).
Only these connections will be allowed to JIT provision Members via SSO when `sso_jit_provisioning` is set to `RESTRICTED`.
sso_active_connections:
type: array
items:
$ref: '#/components/schemas/api_organization_v1_ActiveSSOConnection'
description: >-
An array of active [SAML Connection
references](https://stytch.com/docs/b2b/api/saml-connection-object)
or [OIDC Connection
references](https://stytch.com/docs/b2b/api/oidc-connection-object).
email_allowed_domains:
type: array
items:
type: string
description: >-
An array of email domains that allow invites or JIT provisioning for
new Members. This list is enforced when either `email_invites` or
`email_jit_provisioning` is set to `RESTRICTED`.
Common domains such as `gmail.com` are not allowed. See the [common email domains resource](https://stytch.com/docs/b2b/api/common-email-domains) for the full list.
email_jit_provisioning:
type: string
description: >-
The authentication setting that controls how a new Member can be
provisioned by authenticating via Email Magic Link or OAuth. The
accepted values are:
`RESTRICTED` – only new Members with verified emails that comply with `email_allowed_domains` can be provisioned upon authentication via Email Magic Link or OAuth.
`NOT_ALLOWED` – the default setting, disables JIT provisioning via Email Magic Link and OAuth.
email_invites:
type: string
description: >-
The authentication setting that controls how a new Member can be
invited to an organization by email. The accepted values are:
`ALL_ALLOWED` – any new Member can be invited to join via email.
`RESTRICTED` – only new Members with verified emails that comply with `email_allowed_domains` can be invited via email.
`NOT_ALLOWED` – disable email invites.
auth_methods:
type: string
description: >-
The setting that controls which authentication methods can be used
by Members of an Organization. The accepted values are:
`ALL_ALLOWED` – the default setting which allows all authentication methods to be used.
`RESTRICTED` – only methods that comply with `allowed_auth_methods` can be used for authentication. This setting does not apply to Members with `is_breakglass` set to `true`.
allowed_auth_methods:
type: array
items:
type: string
description: >-
An array of allowed authentication methods. This list is enforced
when `auth_methods` is set to `RESTRICTED`.
The list's accepted values are: `sso`, `magic_link`, `email_otp`, `password`, `google_oauth`, `microsoft_oauth`, `slack_oauth`, `github_oauth`, and `hubspot_oauth`.
mfa_policy:
type: string
description: >-
The setting that controls the MFA policy for all Members in the
Organization. The accepted values are:
`REQUIRED_FOR_ALL` – All Members within the Organization will be required to complete MFA every time they wish to log in. However, any active Session that existed prior to this setting change will remain valid.
`OPTIONAL` – The default value. The Organization does not require MFA by default for all Members. Members will be required to complete MFA only if their `mfa_enrolled` status is set to true.
rbac_email_implicit_role_assignments:
type: array
items:
$ref: >-
#/components/schemas/api_organization_v1_EmailImplicitRoleAssignment
description: |-
Implicit role assignments based off of email domains.
For each domain-Role pair, all Members whose email addresses have the specified email domain will be granted the
associated Role, regardless of their login method. See the [RBAC guide](https://stytch.com/docs/b2b/guides/rbac/role-assignment)
for more information about role assignment.
mfa_methods:
type: string
description: >-
The setting that controls which MFA methods can be used by Members
of an Organization. The accepted values are:
`ALL_ALLOWED` – the default setting which allows all authentication methods to be used.
`RESTRICTED` – only methods that comply with `allowed_mfa_methods` can be used for authentication. This setting does not apply to Members with `is_breakglass` set to `true`.
allowed_mfa_methods:
type: array
items:
type: string
description: >-
An array of allowed MFA authentication methods. This list is
enforced when `mfa_methods` is set to `RESTRICTED`.
The list's accepted values are: `sms_otp` and `totp`.
oauth_tenant_jit_provisioning:
type: string
description: >-
The authentication setting that controls how a new Member can JIT
provision into an organization by tenant. The accepted values are:
`RESTRICTED` – only new Members with tenants in `allowed_oauth_tenants` can JIT provision via tenant.
`NOT_ALLOWED` – the default setting, disables JIT provisioning by OAuth Tenant.
claimed_email_domains:
type: array
items:
type: string
description: A list of email domains that are claimed by the Organization.
first_party_connected_apps_allowed_type:
type: string
description: >-
The authentication setting that sets the Organization's policy
towards first party Connected Apps. The accepted values are:
`ALL_ALLOWED` – the default setting, any first party Connected App in the Project is permitted for use by Members.
`RESTRICTED` – only first party Connected Apps with IDs in `allowed_first_party_connected_apps` can be used by Members.
`NOT_ALLOWED` – no first party Connected Apps are permitted.
allowed_first_party_connected_apps:
type: array
items:
type: string
description: >-
An array of first party Connected App IDs that are allowed for the
Organization. Only used when the Organization's
`first_party_connected_apps_allowed_type` is `RESTRICTED`.
third_party_connected_apps_allowed_type:
type: string
description: >-
The authentication setting that sets the Organization's policy
towards third party Connected Apps. The accepted values are:
`ALL_ALLOWED` – the default setting, any third party Connected App in the Project is permitted for use by Members.
`RESTRICTED` – only third party Connected Apps with IDs in `allowed_first_party_connected_apps` can be used by Members.
`NOT_ALLOWED` – no third party Connected Apps are permitted.
allowed_third_party_connected_apps:
type: array
items:
type: string
description: >-
An array of third party Connected App IDs that are allowed for the
Organization. Only used when the Organization's
`third_party_connected_apps_allowed_type` is `RESTRICTED`.
custom_roles:
type: array
items:
$ref: '#/components/schemas/api_organization_v1_CustomRole'
trusted_metadata:
type: object
additionalProperties: true
description: >-
An arbitrary JSON object for storing application-specific data or
identity-provider-specific data.
created_at:
type: string
description: >-
The timestamp of the Organization's creation. Values conform to the
RFC 3339 standard and are expressed in UTC, e.g.
`2021-12-29T12:33:09Z`.
updated_at:
type: string
description: >-
The timestamp of when the Organization was last updated. Values
conform to the RFC 3339 standard and are expressed in UTC, e.g.
`2021-12-29T12:33:09Z`.
organization_external_id:
type: string
description: A unique identifier for the organization.
sso_default_connection_id:
type: string
description: >-
The default connection used for SSO when there are multiple active
connections.
scim_active_connection:
$ref: '#/components/schemas/api_organization_v1_ActiveSCIMConnection'
description: >-
An active [SCIM Connection
references](https://stytch.com/docs/b2b/api/scim-connection-object).
allowed_oauth_tenants:
type: object
additionalProperties: true
description: >-
A map of allowed OAuth tenants. If this field is not passed in, the
Organization will not allow JIT provisioning by OAuth Tenant.
Allowed keys are "slack", "hubspot", and "github".
required:
- organization_id
- organization_name
- organization_logo_url
- organization_slug
- sso_jit_provisioning
- sso_jit_provisioning_allowed_connections
- sso_active_connections
- email_allowed_domains
- email_jit_provisioning
- email_invites
- auth_methods
- allowed_auth_methods
- mfa_policy
- rbac_email_implicit_role_assignments
- mfa_methods
- allowed_mfa_methods
- oauth_tenant_jit_provisioning
- claimed_email_domains
- first_party_connected_apps_allowed_type
- allowed_first_party_connected_apps
- third_party_connected_apps_allowed_type
- allowed_third_party_connected_apps
- custom_roles
api_organization_v1_ResultsMetadata:
type: object
properties:
total:
type: integer
format: int32
description: >-
The total number of results returned by your search query. If totals
have been disabled for your Stytch Workspace to improve search
performance, the value will always be -1.
next_cursor:
type: string
description: >-
The `next_cursor` string is returned when your search result
contains more than one page of results. This value is passed into
your next search call in the `cursor` field.
required:
- total
api_organization_v1_organizations_SearchQueryOperator:
type: string
enum:
- OR
- AND
api_organization_v1_ActiveSSOConnection:
type: object
properties:
connection_id:
type: string
description: >-
Globally unique UUID that identifies a specific SSO `connection_id`
for a Member.
display_name:
type: string
description: A human-readable display name for the connection.
identity_provider:
type: string
required:
- connection_id
- display_name
- identity_provider
api_organization_v1_EmailImplicitRoleAssignment:
type: object
properties:
domain:
type: string
description: Email domain that grants the specified Role.
role_id:
type: string
description: >-
The unique identifier of the RBAC Role, provided by the developer
and intended to be human-readable.
Reserved `role_id`s that are predefined by Stytch include:
* `stytch_member`
* `stytch_admin`
Check out the [guide on Stytch default Roles](https://stytch.com/docs/b2b/guides/rbac/stytch-default) for a more detailed explanation.
required:
- domain
- role_id
api_organization_v1_CustomRole:
type: object
properties:
role_id:
type: string
description:
type: string
permissions:
type: array
items:
$ref: '#/components/schemas/api_organization_v1_CustomRolePermission'
required:
- role_id
- description
- permissions
api_organization_v1_ActiveSCIMConnection:
type: object
properties:
connection_id:
type: string
description: The ID of the SCIM connection.
display_name:
type: string
description: A human-readable display name for the connection.
bearer_token_last_four:
type: string
bearer_token_expires_at:
type: string
required:
- connection_id
- display_name
- bearer_token_last_four
api_organization_v1_CustomRolePermission:
type: object
properties:
resource_id:
type: string
actions:
type: array
items:
type: string
required:
- resource_id
- actions
securitySchemes:
basicAuth:
type: http
scheme: basic
````