> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-actions-triggers-prototype.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Use the My Organization API to let Auth0 Organization admins manage their own identity providers and verified domains from inside your application.
# My Organization API and Embeddable UI Components
My Organization API and Embeddable UI Components is currently available in Early Access for all customers. By using this feature, you agree to the applicable Free Trial terms in [Okta’s Master Subscription Agreement](https://www.okta.com/legal/). To learn more about Auth0’s product release cycle, read [Product Release Stages](/docs/troubleshoot/product-lifecycle/product-release-stages).
Customers are responsible for ensuring that its use of the My Organization API and Embeddable UI Components comply with its security policies and applicable laws, including any permissions granted to its end users.
The Auth0 My Organization API provides a secure, Organization-scoped interface that allows your business customers to manage their own Organizations within your Auth0 tenant. This API serves as the technical backbone for embedded delegated administration and API-first integrations.
## Core Capabilities
Currently, the API supports management of the following:
* [Auth0 Organization](/docs/manage-users/organizations) details (name, branding, display name)
* Organization-specific configuration, ownership, and relationships
* [Identity Providers (IdPs)](/docs/authenticate/identity-providers) and [SCIM](/docs/authenticate/protocols/scim) provisioning
* Domains and Home Realm Discovery (HRD) setup
The My Organization API allows deep technical control over your integration. For the fastest deployment, we strongly recommend you start with the Embeddable UI components, SDKs, and sample applications. The Embeddable UI components and sample applications significantly reduce the time and effort to deliver a self-service experience to your customers and end users.
## Set up My Organization API
### Activate the My Organization API in Auth0 Dashboard
1. Navigate to **[Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis)**.
2. Locate the My Organization API banner.
3. Select **Activate**.
4. The API appears in your Applications > API list as My Organization API.
Once you activate the My Organization API:
* Auth0 disables the API for all client applications by default.
* You must grant access to applications and roles using [client grants](/docs/get-started/applications/application-access-to-apis-client-grants) or [RBAC](/docs/manage-users/access-control/configure-core-rbac/enable-role-based-access-control-for-apis) policies.
* Your business customers can retrieve Organization details or configure IdPs on behalf of their own Organizations.
#### Default settings
**Auth0 domain vs custom domain**
The My Organization API supports using your canonical Auth0 domain or your custom domain, but you must use the same one throughout the entire process, which includes the following:
* Request an access token
* Set the audience or `aud` value
* Call the My Organization API endpoint
To learn more about using custom domains in Auth0, read [Custom Domains](/docs/customize/custom-domains).
**Access policies**
By default, the My Organization API activates with the following application API access policies:
* `require_client_grant` for user flows
* `deny-all` for machine-to-machine flows
For an application to access the My Organization API on the user’s behalf, create a client grant for that application to define the maximum scopes the application can request. Alternatively, you can allow any application in your tenant to request any scope by changing the user access flows to `allow_all`.
Auth0 does not recommend using `allow_all` for user access flows because the My Organization API exposes sensitive information and operations. You should follow the principle of least privilege to ensure applications get access to what they truly need, minimizing potential security risks.
The final permissions granted to the application will be determined by the intersection of the scopes allowed by the application API access policy, the Role-Based Access Control (RBAC) permissions assigned to the end user, and any user consent given (if applicable).
To learn more about how to manage application API access policies and their associated client grants, read [Application Access to APIs: Client Grants](/docs/get-started/applications/application-access-to-apis-client-grants).
**Token lifetimes**
The My Organization API issues access tokens with a fixed lifetime of 600 seconds (10 minutes). This short duration is a deliberate security measure designed to protect your tenant and its resources.
The My Organization API will always remain opt-in for security reasons. Disabling the API removes access for all connected applications until re-enabled.
### Configure client application attributes
[Create an application](/docs/get-started/auth0-overview/create-applications) in Auth0 to use with the My Organization API. Once created, navigate to **[Auth0 Dashboard > Applications > APIs](https://manage.auth0.com/#/apis)** and authorize the My Organization API, including the scopes you want the application to perform.
Your application must provide the `my_organization_configuration` object or the My Organization API gives an error and rejects the request. You can use the following properties with the `my_organization_configuration` object:
| **Property** | **Description** |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_profile_id` | **Connection Profile ID.** ID of the [Connection Profile](/docs/authenticate/enterprise-connections/connection-profile) used with the application when leveraging the My Organization API. If not provided, My Organization API features that require a Connection Profile to be present will not function. This ID must refer to a valid Connection Profile in the same tenant. |
| `user_attribute_profile_id` | **User Attribute Profile ID**. ID of the [User Attribute Profile](/docs/authenticate/enterprise-connections/user-attribute-profile) used with the application when leveraging the My Organization API. If it is not provided, My Organization API features that require a User Attribute Profile to be present will not function. This ID must refer to a valid User Attribute Profile in the same tenant. |
| `allowed_strategies` | **Array of strings.** Each string is unique and refers to a supported strategy. The supported strategies - the values for the enum - are as follows: `pingfederate`, `ad`, `adfs`, `waad`, `google-apps`, `okta`, `oidc`, and `samlp`. |
| `connection_deletion_behavior` | **Enum (allow, allow\_if\_empty).** Describes how the My Organization API behaves when an end user tries to delete a connection when attempted via the My Organization API from this application. The values and description of the enum are as follows: 1. `allow`: Given the user has the correct scope, a user can delete the connection which results in all users originating from the connection being deleted. 2.`allow_if_empty`: Given the user has the correct scope, a user can only delete the connection if there are no users in the connection. If users are present, the My Organization API will return an error and won’t proceed with the deletion. |
#### Configure client application attributes
To configure the My Organization API’s required attributes:
1. Navigate to **[Dashboard > Applications > APIs](https://manage.auth0.com/#/apis)** and select My Organization API.
2. Select the **Application Access** tab.
3. Choose the application you want to configure and select **Edit**.
4. Configure the following Settings:
A. **Optional**. Configure the Connection Profile.
1. Select an existing Connection Profile or create a new one. For a new Connection Profile:
a. Add a name.
b. Review mappings to ensure the connection attributes reflect the desired settings for new connections.
B. **Optional**. Configure the User Attribute Profile.
1. Add a name.
2. Review mappings to ensure the profile attributes map to your preferred Auth0 attributes.
C. Configure the Supported Identity Providers.
1. Enable one or more identity providers. Customer administrators can select their preferred option from the list of enabled providers.
D. Configure the Connection Deletion Behavior to Allow or Allow if Empty.
1. **Allow**: Given the user has the correct scope, a user can delete the connection which results in all Users originating from the connection being deleted.
2. Allow if Empty: Given the user has the correct scope, a user can only delete the connection if there are no Users in the connection. If users are present, the My Organization API will return an error and won’t proceed with the deletion.
E. Configure the User Access Authorization to Unauthorized, Authorized, or All.
1. **Unauthorized**. No permission allowed.
2. **Authorized**. Select desired permissions.
3. **All**. Includes all existing and future permissions.
F. Configure the Client Credential Access Authorization to Unauthorized, Authorized, or All.
1. **Unauthorized**. No permission allowed.
2. **Authorized**. Select desired permissions.
3. **All**. Includes all existing and future permissions.
5. Select **Save**.
To configure client application attributes programmatically instead of using Auth0 Dashboard, use the available Management API endpoints. To use Management API, you need to get a [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens).
* [`GET` `/api/v2/clients`](https://auth0.com/docs/api/management/v2/clients/get-clients)
* [`POST` `/api/v2/clients`](https://auth0.com/docs/api/management/v2/clients/post-clients)
* [`GET` `/api/v2/clients/{id}`](https://auth0.com/docs/api/management/v2/clients/get-clients-by-id)
* [`PATCH` `/api/v2/clients/{id}`](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id)
## Generate an Access Token
The My Organization API can only be called with a user-bound access token obtained through one of the supported [OAuth 2.0 flows](https://auth0.com/docs/get-started/authentication-and-authorization-flow).
If you’re going to allow the My Organization API to perform sensitive operations, we strongly recommend that you use [step-up authentication](/docs/secure/multi-factor-authentication/step-up-authentication) to enforce additional security policies through multi-factor authentication (MFA).
### Example with Authorization Code Flow
Use [Authorization Code Flow](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow) for confidential Web Applications with a Client Secret.
```bash theme={null}
curl --request POST \
--url 'https://YOUR_DOMAIN/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code' \
--data 'client_id=YOUR_CLIENT_ID' \
--data 'client_secret=YOUR_CLIENT_SECRET' \
--data 'code=AUTH_CODE' \
--data 'redirect_uri=https://yourapp/callback' \
--data 'audience=https://YOUR_DOMAIN/my-org/'
```
**Sample Response**
```json theme={null}
{
"access_token": "eyJz93a...k4laUWw",
"token_type": "Bearer",
"expires_in": 600,
"scope": "read:my_org:details update:my_org:identity_providers"
}
```
### Example with Authorization Code Flow with PKCE
Use [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce) or public applications without a Client Secret, Single-Page Applications, Mobile or Native Applications, and CLI Tools.
```bash theme={null}
curl --request POST \
--url 'https://YOUR_DOMAIN/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=authorization_code' \
--data 'client_id=YOUR_CLIENT_ID' \
--data 'code=AUTH_CODE' \
--data 'code_verifier=CODE_VERIFIER' \
--data 'redirect_uri=https://yourapp/callback' \
--data 'audience=https://YOUR_DOMAIN/my-org/'
```
### Audience
The audience and base URL of the My Organization API is `https://{yourDomain}/my-org/`. Tokens must include the audience `https://YOUR_DOMAIN/my-org/`. Tokens from other APIs (like `/me` or `/api/v2/`) won't work.
### Scopes
| **Scope** | **Description** |
| ----------------------------------------------- | ----------------------------------------------------------------------- |
| `read:my_org:configuration` | Read organization configuration for a client |
| `read:my_org:details` | Read organization details for a client |
| `update:my_org:details` | Update organization details for a client |
| `create:my_org:identity_providers` | Create identity provider for organization |
| `read:my_org:identity_providers` | Read identity providers for organization |
| `update:my_org:identity_providers` | Update identity providers for organization |
| `delete:my_org:identity_providers` | Delete identity providers for organization |
| `update:my_org:identity_providers_detach` | Detach identity provider from organization |
| `create:my_org:identity_providers_domains` | Associate organization domain with identity provider |
| `delete:my_org:identity_providers_domains` | Remove organization domain from identity provider |
| `read:my_org:identity_providers_scim_tokens` | List the Provisioning SCIM tokens for this identity provider |
| `create:my_org:identity_providers_scim_tokens` | Create a Provisioning SCIM token for this identity provider |
| `delete:my_org:identity_providers_scim_tokens` | Delete a Provisioning SCIM token configuration for an identity provider |
| `create:my_org:identity_providers_provisioning` | Create Provisioning configuration for identity provider |
| `read:my_org:identity_providers_provisioning` | Read Provisioning configuration for identity provider |
| `update:my_org:identity_providers_provisioning` | Update Provisioning configuration for identity provider |
| `delete:my_org:identity_providers_provisioning` | Delete Provisioning configuration for identity provider |
| `read:my_org:domains` | Read domains for organization |
| `delete:my_org:domains` | Delete domain for organization |
| `create:my_org:domains` | Create domain for organization |
| `update:my_org:domains` | Update domain for organization |
## Endpoint reference
The My Organization API supports endpoints for configuration, Organization details, identity providers, domains, provisioning configurations, and SCIM Tokens. For a complete reference guide on the endpoints, including the schemas, error codes, etc., refer to our [API Explorer](https://auth0.com/docs/api/myorganization).
## SDK reference
The API is available in an SDK format for Typescript, Java, .NET, Go, and Python. For details on each SDK implementation and for examples on how to leverage the SDK, refer to our [SDK documentation](/docs/libraries).
## User profiles
The My Organization API utilizes [Connection Profiles](/docs/authenticate/enterprise-connections/connection-profile) and [User Attribute Profiles](/docs/authenticate/enterprise-connections/user-attribute-profile) to define the structure, restrictions, and rules for configurations created by third-party customers.
### Connection Profile (CP)
The Connection Profile enables Auth0 developers to specify how the private settings of an Auth0 connection should be configured when created by third parties. For more information on how the Connection Profile works, its attribute mappings and overrides, examples, and how to configure one, read [Connection Profiles](/docs/authenticate/enterprise-connections/connection-profile).
### User Attribute Profile (UAP)
The User Attribute Profile (UAP) provides a consistent way to define, manage, and map user attributes across protocols such as SCIM, SAML, and OIDC. For more information on how the UAP works, its attribute mappings and overrides, examples, and how to configure one, read [User Attribute Profiles](/docs/authenticate/enterprise-connections/user-attribute-profile).
## Rate limits
Rate limits are enforced based on your service tier:
| **Tier** | **Read (RPS)** | **Write (RPS)** |
| ----------------------- | -------------- | --------------- |
| **Free** | 4 | 2 |
| **Public Self-Service** | 8 | 4 |
| **Public Enterprise** | 40 | 20 |
| **Private Basic** | 40 | 20 |
| **Private Performance** | 160 | 80 |
### Per-Organization rate limits
In addition to the service tier rate limits, the My Organization API also enforces per-Organization rate limits. These limits are designed to ensure fair resource allocation and prevent any single Organization from impacting the overall performance of your tenant. By enforcing these boundaries, we mitigate the ‘noisy neighbor’ effect, ensuring that a sudden surge in activity from one Organization does not consume shared resources or impact another within the same environment. Each Organization is allocated a specific number of requests per second (RPS) for both read and write operations.
| **Tier** | **Per-Organization Read (RPS)** | **Per-Organization Write (RPS)** |
| ----------------------- | ------------------------------- | -------------------------------- |
| **Free** | 4 | 2 |
| **Public Self-Service** | 4 | 2 |
| **Public Enterprise** | 8 | 4 |
| **Private Basic** | 8 | 4 |
| **Private Performance** | 16 | 8 |
## Cross-Origin requests
If you intend to call the My Organization API directly from a browser-based application (like a Single Page Application) running on a different domain than your Auth0 tenant, you will encounter browser security policies known as [Cross-Origin Resource Sharing (CORS)](/docs/get-started/applications/set-up-cors). By default, browsers block these cross-origin requests.
To allow your application to successfully make requests to the API, you must add your application’s domain (its “origin”) to your client’s configuration:
1. Navigate to [**Auth0 Dashboard > Applications**](https://manage.auth0.com/#/applications). Select the application to view.
2. Under Cross-Origin Authentication, toggle on Allow Cross-Origin Authentication.
3. Locate Allowed Origins (CORS), and enter your application’s origin URL.
4. Select **Save**.
If you do not need to use CORS for your application, ensure that Allow Cross-Origin Authentication is toggled off. Adding your application’s URL to this list tells Auth0 to trust requests from that origin, allowing your client-side application to access the API.
## Log events
To facilitate granular auditing and monitoring, the My Organization API generates a specific set of log events unique to the API. While your tenant will continue to [emit standard system logs](/docs/deploy-monitor/logs/log-event-type-codes), the table below represents the comprehensive list of event types triggered specifically by My Organization API activity.
These event codes allow you to track activities across all resources managed by the API, specifically: configuration, Organization details, IdPs, and domains. If you want to learn more about log event schemas, you can reference our [GitHub repository](https://github.com/auth0/auth0-log-schemas).
| **Event Code** | **Event** | **Event Description** |
| ------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `my_organization_api_config_failed` | My Organization API Config Failed | Failed API call to the config resource of the My Organization API service |
| `my_organization_api_org_details_succeeded` | My Organization API Org Details Succeeded | Successful API call to the Organization details resource of the My Organization API service |
| `my_organization_api_org_details_failed` | My Organization API Org Details Failed | Failed API call to the Organization details resource of the My Organization API service |
| `my_organization_api_idp_succeeded` | My Organization API Identity Provider Succeeded | Successful API call to the identity provider resource of the My Organization API service |
| `my_organization_api_idp_failed` | My Organization API Identity Provider Failed | Failed API call to the identity provider resource of the My Organization API service |
| `my_organization_api_domain_succeeded` | My Organization API Domain Succeeded | Successful API call to the domain resource of the My Organization API service |
| `my_organization_api_domain_failed` | My Organization API Domain Failed | Failed API call to the domain resource of the My Organization API service |
## Organization connection ownership
The API introduces an ownership model to distinguish between connections managed by the Tenant Admin and those self-managed by the Organization. This is controlled by the `organization_access_level` property.
**Key Property**: `organization_access_level`
| **Enum Value** | **Description** |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `none` | Association assigned by the Tenant Administrator. This connection cannot be seen or edited via the My Organization API. |
| `readonly` | Association assigned by the Tenant Administrator. Can be seen, but cannot be edited via the My Organization API. |
| `limited` | Association assigned by the Tenant Administrator. Limited information and modifications are permissible via the My Organization API, specifically the `show_as_button` and `is_enabled` attributes. |
| `full` | Association assigned by the Tenant Administrator. Users of the My Organization API will be able to modify Organization-specific Connection attributes without additional restrictions, specifically the `show_as_button`, `is_enabled`, options, `display_name`,and `domains` attributes. |
**Management API Endpoints for Connections**:
* `GET` [`/api/v2/organizations/{id}/connections`](https://auth0.com/docs/api/management/v2/organizations/get-organization-connection)
* `POST` [`/api/v2/organizations/{id}/connections`](https://auth0.com/docs/api/management/v2/organizations/post-organization-connection)
* `PATCH` [`/api/v2/organizations/{id}/connections/{id}`](https://auth0.com/docs/api/management/v2/organizations/patch-organization-connection)
* `DELETE` [`/api/v2/organizations/{id}/connections/{id}`](https://auth0.com/docs/api/management/v2/organizations/delete-organization-connection)
When you call the `/connections` endpoints, use the same scopes as you would for the `/enabled_connections` endpoints:
* `create:organization_connections`
* `read:organization_connections`
* `delete:organization_connections`
* `update:organization_connections`
Review the additional schema attributes:
| **Property** | **Description** |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `is_enabled` | **Boolean**. Enables or disables a connection for an Organization. By disabling the connection, it will be possible to keep the values for the connection Object persistent while keeping the connection disabled. |
| `organization_access_level` | **Enum (null, none, readonly, limited, full)**. Determines the type of access a user will have when using the My Organization API: 1. `null` 2. `none` - Association assigned by the Tenant Administrator. This connection cannot be seen or edited via the My Organization API. 3. `readonly` - Association assigned by the Tenant Administrator. This connection can be seen, but cannot be edited via the My Organization API. 4. `limited` - Association assigned by the Tenant Administrator. Limited information and modifications are permissible via the My Organization API. 5. `full` - Association assigned by the Tenant Administrator. Users of the My Organization API will be able to modify the Connection without additional restrictions when using the My Organization API. Note: Regardless of organization\_access\_level, the My Organization API powered modifications are always subject to restrictions enforced by the Connection Profile. |
| `organization_connection_name` | **String**. Stores the name provided when creating the Connection. This field is calculated by the My Organization API by evaluating the Connection Profile's connection\_name\_prefix\_template. This field is only visible and modifiable via the Management API. |
Notes:
* These endpoints accept an optional query parameter of `is_enabled=true/false` and if present only show the connections that have the specified `is_enabled` value.
* `organization_access_level` can only be changed via the Management API.
* If the `name` attribute is not set, it must be populated via the Management API before changing `organization_access_level` from `none` to any other value.
## Auth0 Universal Components
We strongly encourage starting with our embeddable UI components, [Auth0 Universal Components](/docs/get-started/universal-components/universal-components-overview), in favor of using an API-first integration. These resources should significantly reduce your development time and quickly deliver a self-service experience to your customers.