> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev.auth0-mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a connected account request
> Start an authorization flow to link the authenticated user's account with an external identity provider.
export const Scopes = ({scopes = []}) => {
return
Scopes
{"Scopes define permissions and access levels for API requests and authentication tokens."}
;
};
## OpenAPI
````yaml myaccount-api-oas post /connected-accounts/connect
openapi: 3.1.0
info:
title: My Account
version: '1.0'
description: >-
The Auth0 My Account API provides a dedicated set of endpoints for users to
manage their own account information. Customers can use these APIs to build
self-service experiences in their applications or progressively add details
to a user account.
The My Account API operates within the context of the currently logged-in
user and can be used directly within user-facing applications.
:::tip Using Auth0 domain vs. custom domain
The My Account API supports using your canonical Auth0 domain or your custom
domain, but you must use the same one throughout the entire process,
including:
- Getting an access token
- Setting the audience value
- Calling the My Account API endpoint
For more information, read [Custom
Domains](https://auth0.com/docs/customize/custom-domains).
:::
## Activate the My Account API
You can activate the My Account API for your tenant in the Auth0 Dashboard:
1. Navigate to Authentication > APIs.
2. Locate the MyAccount API banner.
3. Select Activate.
By default, the My Account API is created with the following application API
access policies:
`require_client_grant` for user flows
`deny_all` for client (machine-to-machine) flows
For an application to access the My Account API on the user's behalf, you
must explicitly create a client grant for that application, which allows you
to define the maximum scopes the application can request. Alternatively, you
can change the policy for user access flows to allow_all, which allows any
application in your tenant to request any scope from the My Account API.
Because the My Account API exposes sensitive information and operations,
Auth0 does not recommend using allow_all for user access flows. You should
follow a least privilege principle with the My Account API to ensure
applications only 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).
:::info Supported flows
You cannot update the application API policy for client access to the My
Account API, which means you cannot access the My Account API using the
Client Credentials Flow.
:::
To learn more about how to manage application API access policies and their
associated client grants, read [Application Access to APIs: Client
Grants](https://auth0.com/docs/get-started/applications/application-access-to-apis-client-grants).
## Get an access token
You can get an access token for the My Account API in the same way you'd get
an access token for one of your own APIs.
:::info
If you're going to allow the My Account API to perform sensitive operations
(such as enrolling an authentication method), we strongly recommend that you
use [step-up
authentication](https://auth0.com/docs/secure/multi-factor-authentication/step-up-authentication)
to enforce additional security policies through [multi-factor authentication
(MFA)](https://auth0.com/docs/secure/multi-factor-authentication).
:::
If you're using Universal Login, read the following articles:
- [Call Your API Using the Authorization Code
Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow/call-your-api-using-the-authorization-code-flow)
- [Call Your API Using the Authorization Code Flow with
PKCE](https://auth0.com/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce)
If you're using embedded login, read the following articles:
- [Call Your API Using Resource Owner Password
Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/resource-owner-password-flow/call-your-api-using-resource-owner-password-flow)
- [Login Flow with Native Passkeys
API](https://auth0.com/docs/native-passkeys-api#login-flow)
## Examples
### Universal Login with authorization code flow
**Step 1: Request authorization code**
```
curl --request GET \
--url 'https://{yourDomain}/authorize?response_type=code&client_id={yourClientId}&redirect_uri=%7ByourRedirectUri%7D&scope=create%3Ame%3Aauthentication_methods&offline_access=&audience=https%3A%2F%2F{yourDomain}%2Fme%2F'
```
**Step 2: Exchange code for access token**
```
curl --request POST \
--url 'https://{yourDomain}/oauth/token' \
--header 'content-type: application/json' \
--data '{"grant_type": "authorization_code","client_id": "{yourClientId}","client_secret": "{yourClientSecret}","code": "{yourAuthorizationCode}","redirect_uri": "{yourRedirectUri}","audience": "{yourAudience}","scope": "create:me:authentication_methods","offline_access": ""}'
```
### Embedded login with native passkeys
**Step 1: Request login challenge**
```
curl --request POST \
--url 'https://{yourDomain}/passkey/challenge' \
--header 'content-type: application/json' \
--data '{"client_id": "{yourClientId}"}'
```
**Step 2: Authenticate existing user**
```
curl --request POST \
--url 'https://{yourDomain}/oauth/token' \
--header 'content-type: application/json' \
--data '{ "grant_type": "urn:okta:params:oauth:grant-type:webauthn", "client_id": "{yourClientId}", "scope": "create:me:authentication_methods offline_access", "audience": "https://{yourDomain}/me/", "auth_session": "{sessionIdFromTheFirstRequest}", "authn_response": "{authenticatorResponse}"}'
```
servers:
- url: https://{host}/me/v1
variables:
host:
default: auth0.auth0.com
description: Custom or canonical host name
security: []
tags:
- name: factors
description: Factors
x-displayName: Factors
- name: connected-accounts
description: Connected Accounts
x-displayName: Connected Accounts
- name: authentication-methods
description: Authentication Methods
x-displayName: Authentication Methods
- name: consents
description: Consents
x-displayName: Consents
paths:
/connected-accounts/connect:
post:
tags:
- connected-accounts
summary: Create a connected account request
description: >-
Start an authorization flow to link the authenticated user's account
with an external identity provider.
operationId: createConnectedAccountRequest
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConnectedAccountsRequestContent'
required: true
responses:
'201':
$ref: '#/components/responses/CreateConnectedAccountsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'429':
$ref: '#/components/responses/TooManyRequests'
security:
- Bearer-DPoP:
- create:me:connected_accounts
x-codeSamples: []
components:
schemas:
CreateConnectedAccountsRequestContent:
description: Request body for creating an account connection request.
type: object
properties:
connection:
type: string
description: >-
The name of the connection to link the account with (e.g.,
'google-oauth2', 'facebook').
minLength: 1
maxLength: 128
redirect_uri:
type: string
format: uri
description: The URI to redirect to after the connection process completes.
maxLength: 2048
state:
type: string
description: >-
An opaque value used to maintain state between the request and
callback.
minLength: 1
maxLength: 4096
code_challenge:
type: string
description: The PKCE code challenge derived from the code verifier.
minLength: 43
maxLength: 128
code_challenge_method:
type: string
description: >-
The method used to derive the code challenge. Required when
code_challenge is provided.
const: S256
scopes:
type: array
items:
type: string
minLength: 1
maxLength: 255
minItems: 1
maxItems: 100
uniqueItems: true
description: >-
Defines the permissions that the client requests from the Identity
Provider. Must include the standard scopes used to identify the user
(e.g. 'openid', 'email', 'profile'), the scope required to obtain
refresh tokens if needed (e.g. 'offline_access'), and any custom
scopes the client needs to access protected resources.
example:
- openid
- offline_access
- read:tasks
- write:tasks
authorization_params:
$ref: '#/components/schemas/AuthorizationParams'
required:
- connection
- redirect_uri
dependentRequired:
code_challenge:
- code_challenge_method
additionalProperties: false
AuthorizationParams:
title: Authorization Parameters
description: >-
Authorization parameters to be sent to the underlying Identity Provider
(IdP) during the authorization request. These parameters influence how
the IdP processes the authorization flow and what permissions are
requested.
type: object
properties:
acr_values:
type: string
description: >-
Specifies the desired Authentication Context Class Reference values,
which indicate the required level of authentication (e.g.,
multi-factor, passwordless). The Identity Provider (IdP) may enforce
a specific assurance level based on these values.
minLength: 1
maxLength: 1024
audience:
type: string
description: >-
Defines the intended recipient of the access token, typically
indicating who the token is meant for (e.g., an API identifier).
minLength: 1
maxLength: 512
resource:
type: string
description: >-
Specifies which resource server the client is requesting access to
(used in OAuth 2.0 Resource Indicators).
minLength: 1
maxLength: 512
display:
$ref: '#/components/schemas/DisplayEnum'
id_token_hint:
type: string
description: >-
Provides a previously issued id_token to the IdP. It can be used to
suggest which user is being authenticated or to facilitate logout
requests.
minLength: 1
maxLength: 4096
login_hint:
type: string
description: >-
Supplies a hint about the user's identifier (like an email address
or username) to pre-populate the login form.
minLength: 1
maxLength: 255
max_age:
type: integer
description: >-
Indicates the maximum time (in seconds) since the user's last
authentication. If exceeded, the IdP forces the user to
re-authenticate.
minimum: 0
maximum: 2147483647
prompt:
$ref: '#/components/schemas/PromptEnum'
ui_locales:
type: string
description: >-
Suggests the preferred languages for the user interface, passed as a
space-separated list of BCP47 language tags (e.g., 'en', 'es',
'fr').
pattern: ^[a-zA-Z]{2}(-[a-zA-Z]{2})?(\s[a-zA-Z]{2}(-[a-zA-Z]{2})?)*$
minLength: 2
maxLength: 100
additionalProperties: false
CreateConnectedAccountsResponseContent:
type: object
properties:
connect_uri:
type: string
format: uri
description: The base URI to initiate the account connection flow.
auth_session:
type: string
description: The authentication session identifier.
maxLength: 64
connect_params:
$ref: '#/components/schemas/ConnectParams'
expires_in:
type: integer
description: The number of seconds until the ticket expires.
minimum: 1
required:
- connect_uri
- auth_session
- connect_params
- expires_in
additionalProperties: false
ErrorResponse:
properties:
type:
type: string
status:
type: number
title:
type: string
detail:
type: string
validation_errors:
type: array
items:
$ref: '#/components/schemas/ValidationError'
required:
- type
- status
- title
- detail
type: object
additionalProperties: false
DisplayEnum:
enum:
- page
- popup
- touch
- wap
description: >-
Suggests how the IdP should display the authentication interface to the
user.
PromptEnum:
enum:
- none
- login
- consent
- select_account
description: >-
Controls whether the IdP should prompt the user for authentication or
consent.
ConnectParams:
type: object
description: Parameters to be used with the connect URI.
properties:
ticket:
type: string
description: The ticket identifier to be used with the connection URI.
required:
- ticket
additionalProperties: false
ValidationError:
type: object
properties:
detail:
type: string
field:
type: string
pointer:
type: string
source:
type: string
required:
- detail
additionalProperties: false
responses:
CreateConnectedAccountsResponse:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateConnectedAccountsResponseContent'
description: Account connection request created successfully
headers:
x-ratelimit-limit:
$ref: '#/components/headers/XRateLimitLimitHeader'
x-ratelimit-reset:
$ref: '#/components/headers/XRateLimitResetHeader'
x-ratelimit-remaining:
$ref: '#/components/headers/XRateLimitRemainingHeader'
BadRequest:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid input based on schema.
Unauthorized:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized.
Forbidden:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Forbidden.
UnsupportedMediaType:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unsupported Media Type.
TooManyRequests:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Too Many Requests.
headers:
retry-after:
$ref: '#/components/headers/RetryAfterHeader'
x-ratelimit-limit:
$ref: '#/components/headers/XRateLimitLimitHeader'
x-ratelimit-reset:
$ref: '#/components/headers/XRateLimitResetHeader'
x-ratelimit-remaining:
$ref: '#/components/headers/XRateLimitRemainingHeader'
x-auth0-error-kind:
$ref: '#/components/headers/XAuth0ErrorKindHeader'
headers:
XRateLimitLimitHeader:
required: true
description: >-
The maximum number of requests permissible during the limit’s window
window
schema:
type: number
XRateLimitResetHeader:
required: true
description: >-
The anticipated time (as a UNIX timestamp, in seconds) when the bucket
will be replenished
schema:
type: number
XRateLimitRemainingHeader:
required: true
description: >-
The number of remaining requests remaining in the current window until
requests are rejected
schema:
type: number
RetryAfterHeader:
required: true
description: The number of seconds the client should wait before making a new request
schema:
type: number
XAuth0ErrorKindHeader:
description: >-
An indicator that the rate limit exceeded a is global (per tenant)
limit.
schema:
type: string
const: global-rate-limit
securitySchemes:
Bearer-DPoP:
type: http
scheme: bearer
description: Bearer and DPoP tokens are supported depending on the API configuration
````