openapi: 3.0.0
info:
title: Auth0 Authentication actions connections API
description: Auth0 Authentication API. Endpoints for authentication and authorization using OpenID Connect, OAuth 2.0, SAML, WS-Federation, and Passwordless flows.
version: 1.0.0
servers:
- url: '{auth0_domain}'
description: The Authentication API is served over HTTPS.
variables:
auth0_domain:
description: Auth0 domain
default: https://demo.us.auth0.com
tags:
- name: connections
paths:
/connections:
get:
summary: Get All Connections
description: "Retrieves detailed list of all <a href=\"https://auth0.com/docs/authenticate/identity-providers\">connections</a> that match the specified strategy. If no strategy is provided, all connections within your tenant are retrieved. This action can accept a list of fields to include or exclude from the resulting list of connections. \n\nThis endpoint supports two types of pagination:\n<ul>\n<li>Offset pagination</li>\n<li>Checkpoint pagination</li>\n</ul>\n\nCheckpoint pagination must be used if you need to retrieve more than 1000 connections.\n\n<h2>Checkpoint Pagination</h2>\n\nTo search by checkpoint, use the following parameters:\n<ul>\n<li><code>from</code>: Optional id from which to start selection.</li>\n<li><code>take</code>: The total amount of entries to retrieve when using the from parameter. Defaults to 50.</li>\n</ul>\n\n<b>Note</b>: The first time you call this endpoint using checkpoint pagination, omit the <code>from</code> parameter. If there are more results, a <code>next</code> value is included in the response. You can use this for subsequent API calls. When <code>next</code> is no longer included in the response, no pages are remaining.\n"
tags:
- connections
parameters:
- name: per_page
in: query
description: The amount of entries per page. Defaults to 100 if not provided
schema:
type: integer
minimum: 1
maximum: 100
- name: page
in: query
description: The page number. Zero based
schema:
type: integer
minimum: 0
- name: include_totals
in: query
description: true if a query summary must be included in the result, false otherwise. Not returned when using checkpoint pagination. Default <code>false</code>.
schema:
type: boolean
- name: from
in: query
description: Optional Id from which to start selection.
schema:
type: string
- name: take
in: query
description: Number of results per page. Defaults to 50.
schema:
type: integer
minimum: 1
maximum: 100
- name: strategy
in: query
description: Provide strategies to only retrieve connections with such strategies
style: form
explode: true
schema:
type: array
items:
$ref: '#/components/schemas/ConnectionStrategyEnum'
- name: name
in: query
description: Provide the name of the connection to retrieve
schema:
type: string
- name: fields
in: query
description: A comma separated list of fields to include or exclude (depending on include_fields) from the result, empty to retrieve all fields
schema:
type: string
pattern: ^((name)|(display_name)|(strategy)|(options)|(id)|(provisioning_ticket_url)|(metadata)|(show_as_button)|(clients)|(authentication)|(connected_accounts)|(cross_app_access_requesting_app)|(cross_app_access_resource_app)|(enabled_clients))(,((name)|(display_name)|(strategy)|(options)|(id)|(provisioning_ticket_url)|(metadata)|(show_as_button)|(clients)|(authentication)|(connected_accounts)|(cross_app_access_requesting_app)|(cross_app_access_resource_app)|(enabled_clients)))*$
- name: include_fields
in: query
description: <code>true</code> if the fields specified are to be included in the result, <code>false</code> otherwise (defaults to <code>true</code>)
schema:
type: boolean
responses:
'200':
description: The connections were retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/ListConnectionsResponseContent'
'400':
description: Invalid request query string. The message will vary depending on the cause.
'401':
description: Invalid token.
x-description-1: Client is not global.
x-description-2: Invalid signature received for JSON Web Token validation
'403':
description: 'Insufficient scope, expected any of: read:connections'
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: get_connections
x-release-lifecycle: GA
x-operation-name: list
x-operation-request-parameters-name: ListConnectionsQueryParameters
x-operation-group: connections
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- read:connections
post:
summary: Create a Connection
description: 'Creates a new connection according to the JSON object received in <code>body</code>.
<b>Note:</b> If a connection with the same name was recently deleted and had a large number of associated users, the deletion may still be processing. Creating a new connection with that name before the deletion completes may fail or produce unexpected results. '
tags:
- connections
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConnectionRequestContent'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CreateConnectionRequestContent'
responses:
'201':
description: The connection was created.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConnectionResponseContent'
'400':
description: Invalid request body. The message will vary depending on the cause.
x-description-1: Your account is not allowed to set options.set_user_root_attributes
x-description-2: options.set_user_root_attributes can be set only for enterprise connections, social connections or custom database connections (using external users store)
x-description-3: No phone provider configured for the tenant
x-description-4: Passwordless connection cannot be made as delivery method (sms/text) is not supported by the configured Tenant phone provider
x-description-5: custom_password_hash option cannot be set because the universal password hash feature is not enabled for this tenant
x-description-6: The custom_password_hash option is only available for database connections
x-description-7: The action_id field value cannot be empty, null or undefined
x-description-8: The provided custom password hash action id does not exist
x-description-9: The provided action does not support the password hash migration trigger
x-description-10: The provided action must be deployed to be used for password hash migration
'401':
description: Invalid token.
x-description-1: Client is not global.
x-description-2: Invalid signature received for JSON Web Token validation
'403':
description: 'Insufficient scope, expected any of: create:connections'
x-description-1: You reached the limit of entities of this type for this tenant.
x-description-2: You can only create 1 non-Okta enterprise connection(s) for this tenant.
'409':
description: A connection with the same name already exists
x-description-1: A connection with the same name is being deleted, try again later
x-description-2: There is already another connection with some realms from "realms" parameter
x-description-3: There is already a domain connection enabled for strategy
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: post_connections
x-release-lifecycle: GA
x-operation-name: create
x-operation-group: connections
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- create:connections
/connections/{id}:
get:
summary: Get a Connection
description: Retrieve details for a specified <a href="https://auth0.com/docs/authenticate/identity-providers">connection</a> along with options that can be used for identity provider configuration.
tags:
- connections
parameters:
- name: id
in: path
description: The id of the connection to retrieve
required: true
schema:
type: string
- name: fields
in: query
description: A comma separated list of fields to include or exclude (depending on include_fields) from the result, empty to retrieve all fields
schema:
type: string
pattern: ^((name)|(display_name)|(strategy)|(options)|(id)|(provisioning_ticket_url)|(metadata)|(show_as_button)|(clients)|(authentication)|(connected_accounts)|(cross_app_access_requesting_app)|(cross_app_access_resource_app)|(enabled_clients))(,((name)|(display_name)|(strategy)|(options)|(id)|(provisioning_ticket_url)|(metadata)|(show_as_button)|(clients)|(authentication)|(connected_accounts)|(cross_app_access_requesting_app)|(cross_app_access_resource_app)|(enabled_clients)))*$
- name: include_fields
in: query
description: <code>true</code> if the fields specified are to be included in the result, <code>false</code> otherwise (defaults to <code>true</code>)
schema:
type: boolean
responses:
'200':
description: The connection was retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/GetConnectionResponseContent'
'400':
description: Invalid request URI. The message will vary depending on the cause.
x-description-1: Invalid request query string. The message will vary depending on the cause.
'401':
description: Invalid token.
x-description-1: Client is not global.
x-description-2: Invalid signature received for JSON Web Token validation
'403':
description: 'Insufficient scope, expected any of: read:connections'
'404':
description: The connection does not exist.
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: get_connections_by_id
x-release-lifecycle: GA
x-operation-name: get
x-operation-request-parameters-name: GetConnectionRequestParameters
x-operation-group: connections
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- read:connections
delete:
summary: Delete a Connection
description: 'Removes a specific <a href="https://auth0.com/docs/authenticate/identity-providers">connection</a> from your tenant. This action cannot be undone. Once removed, users can no longer use this connection to authenticate.
<b>Note:</b> If your connection has a large amount of users associated with it, please be aware that this operation can be long running after the response is returned and may impact concurrent <a href="https://auth0.com/docs/api/management/v2/connections/post-connections">create connection</a> requests, if they use an identical connection name. '
tags:
- connections
parameters:
- name: id
in: path
description: The id of the connection to delete
required: true
schema:
type: string
responses:
'202':
description: The connection is being deleted.
'204':
description: The connection no longer exists.
'400':
description: Invalid request URI. The message will vary depending on the cause.
'401':
description: Invalid token.
x-description-1: Client is not global.
x-description-2: Invalid signature received for JSON Web Token validation
'403':
description: 'Insufficient scope, expected any of: delete:connections'
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: delete_connections_by_id
x-release-lifecycle: GA
x-operation-name: delete
x-operation-group: connections
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- delete:connections
patch:
summary: Update a Connection
description: 'Update details for a specific <a href="https://auth0.com/docs/authenticate/identity-providers">connection</a>, including option properties for identity provider configuration.
<b>Note</b>: If you use the <code>options</code> parameter, the entire <code>options</code> object is overriden. To avoid partial data or other issues, ensure all parameters are present when using this option.'
tags:
- connections
parameters:
- name: id
in: path
description: The id of the connection to update
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateConnectionRequestContent'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/UpdateConnectionRequestContent'
responses:
'200':
description: The connection was updated.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateConnectionResponseContent'
'400':
description: Invalid request URI. The message will vary depending on the cause.
x-description-1: Invalid request body. The message will vary depending on the cause.
x-description-2: This database contains users. You cannot change "options.enabledDatabaseCustomization" setting.
x-description-3: Your account is not allowed to set options.set_user_root_attributes
x-description-4: The Azure AD common endpoint cannot be enabled for this connection when SCIM is enabled.
x-description-5: The Google Workspace Users API (options.api_enable_users) cannot be disabled for this connection when inbound directory provisioning is enabled.
x-description-6: The Groups extended attribute (options.ext_groups) cannot be disabled for this connection when inbound directory provisioning for groups is enabled.
x-description-7: options.set_user_root_attributes can be set only for enterprise connections, social connections or custom database connections (using external users store)
x-description-8: custom_password_hash option cannot be set because the universal password hash feature is not enabled for this tenant
x-description-9: The custom_password_hash option is only available for database connections
x-description-10: The action_id field value cannot be empty, null or undefined
x-description-11: The provided custom password hash action id does not exist
x-description-12: The provided action does not support the password hash migration trigger
x-description-13: The provided action must be deployed to be used for password hash migration
'401':
description: Invalid token.
x-description-1: Client is not global.
x-description-2: Invalid signature received for JSON Web Token validation
'403':
description: 'Insufficient scope, expected any of: update:connections'
'404':
description: The connection does not exist
'409':
description: The name/client_id tuple has already been used for another connection
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: patch_connections_by_id
x-release-lifecycle: GA
x-operation-name: update
x-operation-group: connections
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- update:connections
/connections/{id}/clients:
get:
summary: Get Enabled Clients for a Connection
description: 'Retrieve all clients that have the specified <a href="https://auth0.com/docs/authenticate/identity-providers">connection</a> enabled.
<b>Note</b>: The first time you call this endpoint, omit the <code>from</code> parameter. If there are more results, a <code>next</code> value is included in the response. You can use this for subsequent API calls. When <code>next</code> is no longer included in the response, no further results are remaining.
'
tags:
- connections
parameters:
- name: id
in: path
description: The id of the connection for which enabled clients are to be retrieved
required: true
schema:
type: string
- name: take
in: query
description: Number of results per page. Defaults to 50.
schema:
type: integer
minimum: 1
maximum: 1000
- name: from
in: query
description: Optional Id from which to start selection.
schema:
type: string
maxLength: 1000
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/GetConnectionEnabledClientsResponseContent'
'400':
description: Invalid request URI. The message will vary depending on the cause.
x-description-1: Invalid query string. The message will vary depending on the cause.
'401':
description: Invalid token.
x-description-1: Invalid signature received for JSON Web Token validation
'403':
description: 'Insufficient scope, expected any of: read:connections'
'404':
description: The connection does not exist
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: get_connection_clients
x-release-lifecycle: GA
x-operation-name: get
x-operation-request-parameters-name: GetConnectionEnabledClientsRequestParameters
x-operation-group:
- connections
- clients
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- read:connections
patch:
summary: Update Enabled Clients for a Connection
tags:
- connections
parameters:
- name: id
in: path
description: The id of the connection to modify
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEnabledClientConnectionsRequestContent'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/UpdateEnabledClientConnectionsRequestContent'
responses:
'204':
description: Success
'400':
description: Invalid request URI. The message will vary depending on the cause.
x-description-1: Invalid request body. The message will vary depending on the cause.
x-description-2: Tenant Phone Provider not set. Connection can not be enable on a client.
x-description-3: Passwordless cannot be enabled for a client, as delivery method (sms/text) is not supported by the configured Tenant phone provider
'401':
description: Invalid token.
x-description-1: Invalid signature received for JSON Web Token validation
'403':
description: 'Insufficient scope, expected any of: update:connections'
'404':
description: The connection does not exist
x-description-1: The client does not exist
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: patch_clients
x-release-lifecycle: GA
x-operation-name: update
x-operation-group:
- connections
- clients
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- update:connections
/connections/{id}/directory-provisioning:
get:
summary: Get a Directory Provisioning Configuration
description: Retrieve the directory provisioning configuration of a connection.
tags:
- connections
parameters:
- name: id
in: path
description: The id of the connection to retrieve its directory provisioning configuration
required: true
schema:
type: string
responses:
'200':
description: The connection's directory provisioning configuration. See <strong>Response Schemas</strong> for schema.
content:
application/json:
schema:
$ref: '#/components/schemas/GetDirectoryProvisioningResponseContent'
'400':
description: Path validation error
x-description-1: The connection strategy does not support inbound directory provisioning
'401':
description: Invalid token.
x-description-1: Invalid signature received for JSON Web Token validation.
x-description-2: Client is not global.
'403':
description: The inbound directory provisioning feature is not enabled for this tenant
x-description-1: 'Insufficient scope; expected any of: read:directory_provisionings.'
'404':
description: The connection does not exist
x-description-1: Directory provisioning configuration not found
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: get_directory-provisioning
x-release-lifecycle: GA
x-operation-name: get
x-operation-group:
- connections
- directoryProvisioning
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- read:directory_provisionings
delete:
summary: Delete a Directory Provisioning Configuration
description: Delete the directory provisioning configuration of a connection.
tags:
- connections
parameters:
- name: id
in: path
description: The id of the connection to delete its directory provisioning configuration
required: true
schema:
type: string
responses:
'204':
description: The connection's directory provisioning configuration has been deleted.
'400':
description: Path validation error
'401':
description: Invalid token.
x-description-1: Invalid signature received for JSON Web Token validation.
x-description-2: Client is not global.
'403':
description: The inbound directory provisioning feature is not enabled for this tenant
x-description-1: 'Insufficient scope; expected any of: delete:directory_provisionings.'
'404':
description: The connection does not exist
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: delete_directory-provisioning
x-release-lifecycle: GA
x-operation-name: delete
x-operation-group:
- connections
- directoryProvisioning
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- delete:directory_provisionings
patch:
summary: Patch a Directory Provisioning Configuration
description: 'Update the directory provisioning configuration of a connection.
'
tags:
- connections
parameters:
- name: id
in: path
description: The id of the connection to create its directory provisioning configuration
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDirectoryProvisioningRequestContent'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/UpdateDirectoryProvisioningRequestContent'
responses:
'200':
description: The connection's directory provisioning configuration was updated. See <strong>Response Schemas</strong> for schema.
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDirectoryProvisioningResponseContent'
'400':
description: Path validation error
x-description-1: Payload validation error
x-description-2: Invalid mapping provided
x-description-3: The connection strategy does not support inbound directory provisioning
x-description-4: The connection cannot be synchronized because setup is incomplete. Please complete the Google Workspace connection administrator setup and try again.
x-description-5: The Groups extended attribute is not enabled on the connection. Select the Groups extended attribute option and go through the setup again.
x-description-6: The Google Workspace Groups API is not enabled on the connection. Select the Enable Groups API option and go through the setup again.
'401':
description: Invalid token.
x-description-1: Invalid signature received for JSON Web Token validation.
x-description-2: Client is not global.
'403':
description: The inbound directory provisioning feature is not enabled for this tenant
x-description-1: Group synchronization is not enabled for this tenant
x-description-2: 'Insufficient scope; expected any of: update:directory_provisionings.'
'404':
description: The connection does not exist
x-description-1: Directory provisioning configuration not found
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: patch_directory-provisioning
x-release-lifecycle: GA
x-operation-name: update
x-operation-group:
- connections
- directoryProvisioning
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- update:directory_provisionings
post:
summary: Create a Directory Provisioning Configuration
description: 'Create a directory provisioning configuration for a connection.
'
tags:
- connections
parameters:
- name: id
in: path
description: The id of the connection to create its directory provisioning configuration
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDirectoryProvisioningRequestContent'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CreateDirectoryProvisioningRequestContent'
responses:
'201':
description: The connection's directory provisioning configuration was created. See <strong>Response Schemas</strong> for schema.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDirectoryProvisioningResponseContent'
'400':
description: Path validation error
x-description-1: Payload validation error
x-description-2: Invalid mapping provided
x-description-3: The connection strategy does not support inbound directory provisioning
x-description-4: The Google Workspace Users API is not enabled on the connection. Select the Enable Users API option and go through the setup again.
x-description-5: The connection cannot be synchronized because setup is incomplete. Please complete the Google Workspace connection administrator setup and try again.
x-description-6: The Groups extended attribute is not enabled on the connection. Select the Groups extended attribute option and go through the setup again.
x-description-7: The Google Workspace Groups API is not enabled on the connection. Select the Enable Groups API option and go through the setup again.
'401':
description: Invalid token.
x-description-1: Invalid signature received for JSON Web Token validation.
x-description-2: Client is not global.
'403':
description: The inbound directory provisioning feature is not enabled for this tenant
x-description-1: Group synchronization is not enabled for this tenant
x-description-2: 'Insufficient scope; expected any of: create:directory_provisionings.'
'404':
description: The connection does not exist
'409':
description: Directory provisioning is already enabled on the specified connection
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: post_directory-provisioning
x-release-lifecycle: GA
x-operation-name: create
x-operation-group:
- connections
- directoryProvisioning
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- create:directory_provisionings
/connections/{id}/directory-provisioning/default-mapping:
get:
summary: Get a Connection's Default Directory Provisioning Attribute Mapping
description: 'Retrieve the directory provisioning default attribute mapping of a connection.
'
tags:
- connections
parameters:
- name: id
in: path
description: The id of the connection to retrieve its directory provisioning configuration
required: true
schema:
type: string
responses:
'200':
description: The connection's directory provisioning default mapping. See <strong>Response Schemas</strong> for schema.
content:
application/json:
schema:
$ref: '#/components/schemas/GetDirectoryProvisioningDefaultMappingResponseContent'
'400':
description: Path validation error
x-description-1: The connection strategy does not support inbound directory provisioning
'401':
description: Invalid token.
x-description-1: Invalid signature received for JSON Web Token validation.
x-description-2: Client is not global.
'403':
description: The inbound directory provisioning feature is not enabled for this tenant
x-description-1: 'Insufficient scope; expected any of: read:directory_provisionings.'
'404':
description: The connection does not exist
x-description-1: Directory provisioning configuration not found
'429':
description: Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
operationId: get_directory_provisioning_default_mapping
x-release-lifecycle: GA
x-operation-name: getDefaultMapping
x-operation-group:
- connections
- directoryProvisioning
security:
- bearerAuth: []
- oAuth2ClientCredentials:
- read:directory_provisionings
/connections/{id}/directory-provisioning/synchronizations:
post:
summary: Request an On-demand Synchronization of the Directory
description: 'Request an on-demand synchronization of the directory.
'
tags:
- connections
parameters:
- name: id
in: path
description: The id of the connection to trigger synchronization for
# --- truncated at 32 KB (125 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/auth0/refs/heads/main/openapi/auth0-connections-api-openapi.yml