> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Especificaciones de la API de autenticación de Auth0 para claves de acceso nativas
# API de claves de acceso nativas
export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => {
const stageTextMap = {
"beta": "Beta",
"ea": "Acceso anticipado"
};
const stageText = stageTextMap[stage] || "una etapa de lanzamiento del producto";
const prsLink = "/docs/troubleshoot/product-lifecycle/product-release-stages";
const linkify = (text, url) => {
return {text};
};
const includeDetails = (plans, contact, terms) => {
const hasDetails = terms || plans || contact;
if (!hasDetails) return null;
return
{plans && <>Esta funcionalidad está disponible en los {linkify(`planes ${plans}`, "https://auth0.com/pricing")}. }
{contact && "Para participar, ponte en contacto con " + contact + ". "}
{terms && <>Al usar esta funcionalidad, aceptas los términos aplicables de la prueba gratuita incluidos en el {linkify("Master Subscription Agreement", "https://www.okta.com/legal")} de Okta.}
;
};
return
La funcionalidad {feature} está en {linkify(stageText, prsLink)}.
{includeDetails(plans, contact, terms)}
;
};
Las claves de acceso son una alternativa resistente al phishing frente a las formas tradicionales de autenticación (como username y contraseña) y ofrecen una experiencia de usuario más sencilla y segura. Para conocer todos los detalles de implementación, consulte [Native Passkeys for Mobile Applications](/es/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications).
Las claves de acceso nativas usan una combinación de Auth0 y las API nativas de iOS o Android para integrar los flujos de desafío directamente en su aplicación móvil. Los endpoints que se enumeran a continuación son un subconjunto de la API de autenticación de Auth0. Para obtener más información sobre cómo usar esta API, consulte la [Introducción a la API de autenticación](https://auth0.com/docs/api/authentication#introduction).
Las claves de acceso tienen tres flujos relacionados:
* **Registro**: Crea una cuenta de usuario nueva con una clave de acceso como método principal de autenticación.
* **Inscripción**: Agrega una clave de acceso como método de autenticación a la cuenta de un usuario existente.
* **Inicio de sesión**: Solicita a un usuario existente que se autentique con una clave de acceso asociada a su cuenta.
## Flujo de registro
### Solicitar desafío para el registro
`POST /passkey/register`
Inicia el flujo de registro de clave de acceso para un nuevo usuario.
Como respuesta, Auth0 devuelve [PublicKeyCredentialCreationOptions](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialcreationoptions) y un id de sesión. Consulta `timeout` en `authn_params_public_key` de la respuesta para ver el tiempo de espera de la sesión.
El flujo de registro de clave de acceso admite Organizaciones mediante el parámetro `organization`, según el comportamiento descrito en [Flujos de inicio de sesión para Organizaciones](/es/docs/manage-users/organizations/login-flows-for-organizations). Si tu aplicación está configurada para **Usuarios empresariales**, debes proporcionar el parámetro `organization` y un valor válido de nombre o identificador de Organización. Después de que el usuario registre una clave de acceso, Auth0 lo inscribe en la Organización proporcionada.
#### Parámetros de la solicitud
| Parámetro | Descripción |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id` | **Obligatorio**. El `client_id` de su aplicación. |
| `realm` | **Opcional**. El nombre de la conexión que se asociará con este usuario.
Si no se especifica una conexión, se usa el directorio predeterminado de su inquilino. |
| `user_profile` | **Obligatorio**. Un objeto que contiene información de identificación del usuario. De forma predeterminada, esto incluye un `email` válido y un `name` de visualización opcional.
Si ha habilitado [Identificadores flexibles](/es/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers) para su conexión de base de datos, puede usar una combinación de `email`, `phone_number` o `username` como identificadores. Estas opciones pueden ser obligatorias u opcionales y deben coincidir con la configuración de sus Identificadores flexibles.
Si el identificador proporcionado (como `email`) ya existe en el directorio, debe pedirse al usuario que, en su lugar, complete el flujo de inicio de sesión. |
#### Ejemplos de código
##### Solicitud
```text lines theme={null}
POST /passkey/register
Content-Type: application/json
{
"client_id": "{YOUR_CLIENT_ID}",
"realm": "{OPTIONAL_CONNECTION}",
"user_profile": {
"email": "{VALID_EMAIL_ADDRESS}",
"name": "{OPTIONAL_USER_DISPLAY_NAME}",
}
}
```
##### Respuesta
```json lines expandable theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
{
"authn_params_public_key": {
"challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
"timeout": {MILLISECONDS},
"rp": {
"id": "{THE_CUSTOM_DOMAIN}",
"name": "{THE_CUSTOM_DOMAIN}"
},
"pubKeyCredParams": [
{ "type": "public-key", "alg": -8 },
{ type: 'public-key', alg: -7 },
{ type: 'public-key', alg: -257 }
],
"authenticatorSelection": {
"residentKey": "required",
"userVerification": "preferred"
},
"user": {
"id": "{GENERATED_ID}",
"name": "{USER-ENTERED_IDENTIFIER}",
"displayName": "{USER-ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING}"
}
},
"auth_session": "{SESSION_ID}"
}
```
* Una vez completada la solicitud de desafío, la aplicación puede continuar el proceso de registro del usuario mediante las API nativas de [Android](https://developer.android.com/identity/passkeys/create-passkeys) o [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service).
* A continuación, debe [autenticar al nuevo usuario](#authenticate-new-user) con la información obtenida a través de las API nativas para completar el flujo.
### Autenticar a un usuario nuevo
Actualmente no se admite el registro nativo con claves de acceso si en la misma conexión se requiere la verificación mediante OTP por SMS/correo electrónico durante el registro.
`POST /oauth/token`
Usa el endpoint de token para autenticar al usuario con las credenciales proporcionadas, crear su cuenta y devolver los tokens solicitados.
El parámetro `authn_response` se basa en la [especificación de la API de autenticación web (WebAuthn)](https://www.w3.org/TR/webauthn-3/). En el flujo nativo de claves de acceso, la información que se envía a este endpoint puede recuperarse mediante las API nativas de su aplicación móvil:
* [Documentación de registro para Android](https://developer.android.com/identity/passkeys/create-passkeys)
* [Documentación de registro para iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service)
#### Parámetros de la solicitud
| Parámetro | Descripción |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `grant_type` | **Obligatorio**. Incluya el valor: `urn:okta:params:oauth:grant-type:webauthn` |
| `client_id` | **Obligatorio**. El `client_id` de su aplicación |
| `realm` | **Opcional**. El nombre de la conexión que se asociará al usuario. Si no se especifica una conexión, se usa el directorio predeterminado de su inquilino. |
| `scope` | **Opcional**. Use `openid` para obtener un token de ID o `openid profile email` para incluir información del perfil del usuario en el token de ID. |
| `audience` | **Opcional**. Identificador de la API para la que desea obtener un token de acceso. |
| `auth_session` | **Obligatorio**. ID de sesión devuelto durante la solicitud inicial del desafío de passkey. |
| `authn_response` | **Obligatorio**. Un objeto que contiene los siguientes elementos:- `id`
- `rawId`
- `type`
- `authenticatorAttachment`
- `response`
|
| `authn_response.id` | **Obligatorio**. ID de credencial Base64URL. |
| `authn_response.rawId` | **Obligatorio**. ID de credencial Base64URL. |
| `authn_response.type` | **Obligatorio**. Incluya el valor: `public-key` |
| `authn_response.authenticatorAttachment` | **Obligatorio**. Incluya los valores:- `platform`
- `cross-platform`
|
| `authn_response.response` | **Obligatorio**. Un objeto que contiene los siguientes elementos: - `clientDataJSON`: Contiene una serialización compatible con JSON de los datos del cliente; heredada de [AuthenticatorResponse](https://www.w3.org/TR/webauthn-3/#authenticatorresponse).
- `attestationObject`: Contiene datos del autenticador y una declaración de atestación; heredada de [AuthenticatorResponse](https://www.w3.org/TR/webauthn-3/#authenticatorresponse).
|
#### Ejemplos de código
##### Solicitud
```text lines theme={null}
POST /oauth/token
Content-Type: application/json
{
"grant_type": "urn:okta:params:oauth:grant-type:webauthn",
"client_id": "{YOUR_CLIENT_ID}",
"realm": "{OPTIONAL_CONNECTION}",
"scope": "{OPTIONAL_REQUESTED_SCOPE}",
"audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
"auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
"authn_response": {
"id": "{BASE64URL_ID}",
"rawId": "{BASE64URL_RAWID}",
"type": "public-key",
"authenticatorAttachment": "platform|cross-platform",
"response": {
"clientDataJSON": "{BASE64URL_CLIENT_DATA_JSON}",
"attestationObject": "{BASE64URL_ATTESTATION_OBJECT}",
{OTHER_PROPERTIES}
},
}
}
```
##### Respuesta
```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "{BASE64_TOKEN}",
"refresh_token": "{BASE64_TOKEN}",
"id_token": "{BASE64_TOKEN}",
"token_type": "Bearer",
"expires_in": {SECONDS}
}
```
## Flujo de inscripción
Registrar una nueva clave de acceso para un usuario implica un proceso de dos pasos mediante la My Account API. Este flujo garantiza que la inscripción de la clave de acceso se inicie de forma segura y luego se verifique.
Antes de iniciar el flujo de inscripción, asegúrate de tener un token de acceso con el scope `create:me:authentication_methods` para el endpoint `/me`.
### Iniciar la inscripción de clave de acceso
`POST /me/v1/authentication-methods`
El primer paso es iniciar el proceso de inscripción. Para ello, haga una solicitud POST al endpoint `/me/v1/authentication-methods`.
#### Parámetros de la solicitud
| Parámetro | Descripción |
| ------------ | ------------------------------------------------------------------------------ |
| `type` | **Obligatorio**. Incluya el valor `public-key`. |
| `connection` | **Opcional**. El nombre de la conexión en la que se creará la clave de acceso. |
| `identity` | **Opcional**. La identidad del usuario. Se usa con cuentas vinculadas. |
#### Ejemplos de código
##### Solicitud
```json lines theme={null}
{
"type": "passkey",
"connection": "CONNECTION_NAME",
"identity": "IDENTITY_USER_ID"
}
```
##### Respuesta
```json lines theme={null}
{
"authn_params_public_key": {
"challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION",
"timeout": MILLISECONDS,
"rp": {
"id": "CUSTOM_DOMAIN",
"name": "CUSTOM_DOMAIN"
},
"pubKeyCredParams": [
{ type: 'public-key', alg: -8 },
{ type: 'public-key', alg: -7 },
{ type: 'public-key', alg: -257 }
],
"authenticatorSelection": {
"residentKey": "required",
"userVerification": "preferred"
},
"user": {
"id": "GENERATED_ID",
"name": "USER_ENTERED_IDENTIFIER",
"displayName": "USER_ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING"
}
},
"auth_session": "SESSION_ID"
}
```
* La propiedad `auth_session` del cuerpo de la respuesta es el identificador de la sesión de autenticación actual. Debe pasarse al endpoint `/verify`.
* Una vez completada la solicitud de desafío, su aplicación puede continuar con el proceso de inscripción del usuario mediante las API nativas de [Android](https://developer.android.com/identity/passkeys/create-passkeys) o [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service). Se le pedirá al usuario que cree una clave de acceso con su autenticador (como un escáner de huellas digitales, una llave de seguridad o un teléfono).
### Verificar la inscripción de la clave de acceso
`POST /me/v1/authentication-methods/passkey|new/verify`
El ID de la ruta siempre es `passkey|new` para las nuevas inscripciones.
Una vez que el usuario haya creado correctamente la clave de acceso con su autenticador, la aplicación cliente recibirá una `AuthenticatorAttestationResponse` de la API de WebAuthn. Esta respuesta debe enviarse al servicio de Auth0 para completar y verificar la inscripción.
* [Documentación de registro para Android](https://developer.android.com/identity/passkeys/create-passkeys)
* [Documentación de registro para iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service)
#### Parámetros de la solicitud
| Parámetros | Descripción |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `auth_session` | **Obligatorio**. El identificador de sesión recibido en la respuesta de la primera solicitud POST a `/me/v1/authentication-methods`. |
| `authn_response` | **Obligatorio**. El parámetro `authn_response` se basa en la especificación de la API de autenticación web (WebAuthn). En el flujo nativo de clave de acceso, la información que se envía a este endpoint puede recuperarse mediante las API nativas de tu aplicación móvil. |
| `authn_response.id` | **Obligatorio**. id de la credencial en Base64URL. |
| `authn_response.rawId` | **Obligatorio**. id de la credencial en Base64URL. |
| `authn_response.type` | **Obligatorio**. Incluye el valor: `public-key`. |
| `authn_response.authenticatorAttachment` | **Obligatorio**. Incluye los valores: `platform`, `cross-platform`. |
| `authn_response.response` | **Obligatorio**. Un objeto que contiene los siguientes elementos: - `clientDataJson`: Contiene una serialización compatible con JSON de los datos del cliente; heredada de `AuthenticatorResponse`.
- `attestationObject`: Contiene datos del autenticador y una declaración de atestación; heredada de `AuthenticatorResponse`.
|
#### Ejemplos de código
##### Solicitud
```json lines theme={null}
{
"auth_session": "SESSION_ID",
"authn_response": {
"id": "BASE64URL_ID",
"rawId": "BASE64URL_RAWID",
"type": "public-key",
"authenticatorAttachment": "platform|cross-platform",
"response": {
"clientDataJSON": "BASE64URL_CLIENT_DATA_JSON",
"attestationObject": "BASE64URL_ATTESTATION_OBJECT"
}
}
}
```
Una vez completado correctamente este paso, la clave de acceso quedará inscrita para el usuario y podrá utilizarse en autenticaciones posteriores.
## Flujo de autenticación
### Solicitar desafío de inicio de sesión
`POST /passkey/challenge`
Inicia el flujo de inicio de sesión con clave de acceso para un usuario existente que guardó una clave de acceso en su cuenta durante el registro inicial.
Como respuesta, Auth0 devuelve [PublicKeyCredentialRequestOptions](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialrequestoptions), un ID de sesión y un identificador de parte de confianza `rpId`. Consulta `timeout` en `authn_params_public_key` de la respuesta para conocer el tiempo de espera de la sesión. El `rpId` devuelto en la respuesta es el identificador que el dispositivo nativo (iOS/Android) usa para buscar credenciales guardadas vinculadas a un dominio. Para que una clave de acceso creada en una aplicación web (por ejemplo, `example.com`) esté disponible en el flujo nativo, el `rpId` devuelto debe coincidir con el `rpId` de la web. Para obtener más información sobre cómo personalizar el RP ID de tu inquilino, consulta [Configurar la política de claves de acceso](/es/docs/authenticate/database-connections/passkeys/configure-passkey-policy#configure-relying-party-id-rp-id).
El flujo de inicio de sesión con clave de acceso admite Organizaciones mediante el parámetro `organization`, según el comportamiento descrito en [Flujos de inicio de sesión para Organizaciones](/es/docs/manage-users/organizations/login-flows-for-organizations). Si tu aplicación está configurada para **Usuarios empresariales**, debes proporcionar el parámetro `organization` y un nombre o identificador de Organización válidos.
Todos los tokens emitidos se generan en el contexto de la Organización proporcionada. Si habilitaste [Membresía automática](/es/docs/manage-users/organizations/login-flows-for-organizations#auto-membership) para tu Organización, el usuario se inscribe automáticamente en la Organización después de autenticarse correctamente.
#### Parámetros de la solicitud
| Parámetro | Descripción |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id` | **Obligatorio**. El `client_id` de tu aplicación. |
| `realm` | **Opcional**. El nombre de la conexión que se asociará con el usuario.
Si no se especifica una conexión, se usará el directorio predeterminado de tu inquilino. |
#### Ejemplos de código
##### Solicitud
```text lines theme={null}
POST /passkey/challenge
Content-Type: application/json
{
"client_id": "{YOUR_CLIENT_ID}",
"realm": "{OPTIONAL_CONNECTION}"
}
```
##### Respuesta
```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
{
"authn_params_public_key": {
"challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}",
"timeout": {AUTH_TIMEOUT_IN_MILLISECONDS},
"rpId": "{CUSTOM_DOMAIN}",
"userVerification": "preferred"
},
"auth_session": "{SESSION_ID}"
}
```
* Una vez completada la solicitud de desafío, tu aplicación puede continuar con el proceso de inicio de sesión mediante las API nativas de [Android](https://developer.android.com/identity/passkeys/sign-in-with-passkeys) o [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account).
* Luego, debes [autenticar al usuario existente](#authenticate-existing-user) con la información obtenida a través de las API nativas para completar el flujo.
### Autenticar a un usuario existente
`POST /oauth/token`
Usa el endpoint de token para autenticar al usuario con las credenciales proporcionadas y devolver los tokens solicitados.
El parámetro `authn_response` se basa en la [especificación de la API de autenticación web (WebAuthn)](https://www.w3.org/TR/webauthn-3/). En el flujo nativo de claves de acceso, la información enviada a este endpoint puede recuperarse a través de las API nativas de tu aplicación móvil:
* [Documentación de inicio de sesión para Android](https://developer.android.com/identity/passkeys/sign-in-with-passkeys)
* [Documentación de inicio de sesión para iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account)
#### Parámetros de la solicitud
| Parámetro | Descripción |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `grant_type` | **Obligatorio**. Incluya el valor: `urn:okta:params:oauth:grant-type:webauthn` |
| `client_id` | **Obligatorio**. El `client_id` de su aplicación |
| `realm` | **Opcional**. El nombre de la conexión que se asociará al usuario. Si no se especifica una conexión, se usa el directorio predeterminado de su inquilino. |
| `scope` | **Opcional**. Use `openid` para obtener un token de ID o `openid profile email` para incluir información del perfil del usuario en el token de ID. |
| `audience` | **Opcional**. Identificador de la API para la que desea obtener un token de acceso. |
| `auth_session` | **Obligatorio**. ID de sesión devuelto durante la solicitud inicial del desafío de clave de acceso. |
| `authn_response` | **Obligatorio**. Un objeto que contiene los siguientes elementos:- `id`
- `rawId`
- `type`
- `authenticatorAttachment`
- `response`
- `clientExtensionResults`
|
| `authn_response.id` | **Obligatorio**. ID de credencial en Base64URL. |
| `authn_response.rawId` | **Obligatorio**. ID de credencial en Base64URL. |
| `authn_response.type` | **Obligatorio**. Incluya el valor: `public-key` |
| `authn_response.authenticatorAttachment` | **Opcional**. Incluya los valores:- `platform`
- `cross-platform`
|
| `authn_response.response` | **Obligatorio**. Un objeto que contiene los siguientes elementos: - `authenticatorData`: Contiene los [datos del autenticador](https://www.w3.org/TR/webauthn-3/#authenticator-data) devueltos por el autenticador.
- `clientDataJSON`: Contiene una serialización compatible con JSON de los datos del cliente; heredada de [AuthenticatorResponse](https://www.w3.org/TR/webauthn-3/#authenticatorresponse).
- `signature`: Firma en Base64URL devuelta por el autenticador.
- `userHandle`: Identificador en Base64URL de la cuenta de usuario, devuelto como `user.id` en el paso de registro.
|
| `authn_response.clientExtensionResults` | **Opcional**. Contiene los resultados del procesamiento de las extensiones del cliente solicitadas por la parte de confianza. |
#### Ejemplos de código
##### Solicitud
```text lines theme={null}
POST /oauth/token
Content-Type: application/json
{
"grant_type": "urn:okta:params:oauth:grant-type:webauthn",
"client_id": "{YOUR_CLIENT_ID}",
"realm": "{OPTIONAL_CONNECTION}",
"scope": "{OPTIONAL_REQUESTED_SCOPE}",
"audience": "{OPTIONAL_REQUESTED_AUDIENCE}"
"auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}",
"authn_response": {
"id": "{BASE64URL_ID}",
"rawId": "{BASE64URL_RAWID}",
"type": "public-key",
"authenticatorAttachment": "platform|cross-platform",
"response": {
"authenticatorData": "{BASE64URL_AUTHENTICATORDATA}",
"clientDataJSON": "{BASE64URL_CLIENTDATAJSON}",
"signature": "{BASE64URL_SIGNATURE}",
"userHandle": "{BASE64URL_USERHANDLE}"
},
"clientExtensionResults": {OPTIONAL_OBJECT}
},
}
```
##### Respuesta
```json lines theme={null}
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "{BASE64_TOKEN}",
"refresh_token": "{BASE64_TOKEN}",
"id_token": "{BASE64_TOKEN}",
"token_type": "Bearer",
"expires_in": {SECONDS}
}
```