> ## 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.

> Aprenda a configurar los metadatos del Token de actualización de Auth0

# Configurar los metadatos del Token de actualización

<Warning>
  Los metadatos del Token de actualización están actualmente en Early Access solo para clientes Enterprise. Al usar esta funcionalidad, acepta los términos aplicables de la prueba gratuita del [Master Subscription Agreement](https://www.okta.com/legal) de Okta. Para obtener más información sobre el ciclo de lanzamiento de productos de Auth0, consulte [Etapas de lanzamiento del producto](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages).
</Warning>

Para configurar los metadatos del Token de actualización, puede usar una [Action de Post-Login](/es/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger) de Auth0 y la [Management API](https://auth0.com/docs/api/management/v2).

<div id="auth0-post-login-actions">
  ## Actions de Auth0 Post-Login
</div>

Puede gestionar operaciones CRUD de metadatos del token de actualización mediante los objetos `api.refreshToken` con una [Action Post-Login](/es/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger). Esto le permite gestionar el metadato del token de actualización según la lógica específica del usuario o del contexto.

### Recupera los metadatos existentes del token de actualización

Usa el objeto `event.refresh_token.metadata` para leer los metadatos del token de actualización:

```javascript lines theme={null}
const deviceName = event.refresh_token?.metadata?.deviceName;
```

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  El objeto `event.refresh_token.metadata` incluye metadatos establecidos en:

  * Actions previas dentro del mismo flujo
  * Transacciones anteriores si el token de actualización se reutilizó durante un intercambio de token de actualización
</Callout>

<div id="add-or-update-existing-metadata">
  ### Agregue o actualice metadatos existentes
</div>

Use el método `api.refreshToken.setMetadata()` para establecer o actualizar los metadatos del Token de actualización:

```javascript lines theme={null}
api.refreshToken.setMetadata("deviceName", "Auth0's iPhone");
```

Los cambios están disponibles de inmediato en el objeto `event.refresh_token` en las Actions siguientes.

### Eliminar metadatos del Token de actualización

Utilice los siguientes métodos de `api.refreshToken` para eliminar los metadatos del Token de actualización:

* `api.refreshToken.deleteMetadata("key")` elimina los metadatos especificados del Token de actualización

* `api.refreshToken.evictMetadata()` elimina todos los metadatos del Token de actualización

Para obtener más información sobre estos objetos, consulte:

* [Objeto Event](/es/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object): Obtenga más información sobre el objeto Event del Token de actualización y sus propiedades.
* [Objeto API](/es/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object): Obtenga más información sobre el objeto API del Token de actualización y sus métodos.

<div id="auth0-management-api">
  ## Auth0 Management API
</div>

Puede gestionar las solicitudes CRUD (crear, reemplazar, actualizar y eliminar) de los metadatos del token de actualización con la Management API:

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Las llamadas al endpoint `/api/v2/refresh-tokens/{id}` requieren un [token de acceso de la Management API](/es/docs/secure/tokens/access-tokens) con el scope `update:refresh_tokens`.
</Callout>

<div id="retrieve-existing-refresh-token-metadata">
  ### Recuperar los metadatos de un token de actualización existente
</div>

Haga una solicitud `GET` al endpoint [`/api/v2/refresh-tokens/{id}`](https://auth0.com/docs/api/management/v2/refresh-tokens/get-refresh-token):

```bash lines theme={null}
GET /api/v2/refresh-tokens/{id}
```

<div id="add-or-update-existing-refresh-token-metadata">
  ### Agregue o actualice los metadatos de un Token de actualización existente
</div>

Haga una solicitud `PATCH` al endpoint [`/api/v2/refresh-tokens/{id}`](https://auth0.com/docs/api/management/v2/refresh-tokens/patch-refresh-token):

```bash lines theme={null}
PATCH /api/v2/refresh-tokens/{id}
Content-Type: application/json

{
  "refresh_token_metadata": {
    "my_metadata": "my new metadata"
  }
}
```

<div id="delete-refresh-token-metadata">
  ### Eliminar los metadatos del token de actualización
</div>

Haz una solicitud `PATCH` al endpoint [`/api/v2/refresh-tokens/{id}`](https://auth0.com/docs/api/management/v2/refresh-tokens/patch-refresh-token) con un objeto de metadatos vacío:

```bash lines theme={null}
PATCH /api/v2/refresh-tokens/{id}
Content-Type: application/json

{
  "refresh_token_metadata": {}
}
```

<div id="use-case-store-and-consume-organization-context">
  ## Caso de uso: Almacenar y utilizar el contexto de la organización
</div>

Puede usar los metadatos del Token de actualización para almacenar el contexto de la organización durante la autenticación inicial y utilizarlo más adelante durante los intercambios del Token de actualización. Esto resulta útil para sistemas posteriores, como las canalizaciones de auditoría, análisis y revocación.

<div id="set-metadata-at-initial-authentication">
  ### Establecer metadatos en la autenticación inicial
</div>

Durante el primer inicio de sesión, establezca el contexto de la organización en los metadatos del token de actualización:

```javascript lines theme={null}
/**
 * Action Post-Login
 * Agrega el contexto de organización a los metadatos del Token de actualización durante la autenticación inicial.
 * Estos metadatos estarán disponibles en los intercambios posteriores del Token de actualización.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Continuar solo si la transacción tiene como destino una Organización
  if (!event.organization) return;

  // Mantener los valores cortos y solo como cadenas (los metadatos del Token de actualización requieren cadenas)
  const orgId = String(event.organization.id || "");
  const orgSlug = String(event.organization.name || "");
  const orgDisplay = String(event.organization.display_name || orgSlug);

  // Establecer metadatos: se almacenarán junto con el Token de actualización
  api.refreshToken.setMetadata("org_id", orgId);
  api.refreshToken.setMetadata("org_slug", orgSlug);
  api.refreshToken.setMetadata("org_name", orgDisplay);
};
```

<div id="consume-metadata-during-refresh-token-exchange">
  ### Consumir metadatos durante el intercambio del token de actualización
</div>

Durante un intercambio del token de actualización, el objeto `event.refresh_token` está disponible y puedes leer los metadatos almacenados previamente:

```javascript lines theme={null}
/**
 * Post-Login Action
 * Consume el contexto de organización de los metadatos del Token de actualización durante el intercambio de tokens.
 * Úselo para aplicar políticas o agregar claims según el contexto de autenticación original.
 */
exports.onExecutePostLogin = async (event, api) => {
  // Verifica si se trata de un intercambio de Token de actualización (event.refresh_token existe)
  if (!event.refresh_token) return;

  // Lee el contexto de organización almacenado durante la autenticación inicial
  const orgId = event.refresh_token.metadata?.org_id;
  const orgSlug = event.refresh_token.metadata?.org_slug;

  if (orgId) {
    // Usa el contexto de organización para lógica condicional
    console.log(`Refresh token exchange for organization: ${orgSlug}`);
    
    // Ejemplo: Agrega custom claims según el contexto de organización original
    api.accessToken.setCustomClaim("org_id", orgId);
  }
};
```

<div id="retrieve-via-management-api">
  ### Obtener mediante Management API
</div>

También puede consultar los metadatos del Token de actualización mediante el endpoint [/api/v2/refresh-tokens/{id}](https://auth0.com/docs/api/management/v2/refresh-tokens/get-refresh-token):

```bash lines theme={null}
GET /api/v2/refresh-tokens/{id}
```

Respuesta de ejemplo:

```json lines theme={null}
{
  "refresh_token_metadata": {
    "org_id": "org_abc123",
    "org_slug": "acme",
    "org_name": "Acme Corp"
  }
}
```

<div id="use-case-track-and-validate-device-information">
  ## Caso de uso: Registrar y validar la información del dispositivo
</div>

Puede usar los metadatos del Token de actualización para recopilar información del dispositivo durante la autenticación inicial y validarla en los intercambios posteriores del Token de actualización con fines de seguridad.

<div id="set-device-information-at-initial-authentication">
  ### Establecer la información del dispositivo durante la autenticación inicial
</div>

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // Solo establecer información del dispositivo si NO es un intercambio de Token de actualización
  // (es decir, esta es la autenticación inicial)
  if (event.refresh_token) return;

  // Almacenar información del dispositivo en los metadatos del Token de actualización
  api.refreshToken.setMetadata("initial_ip", event.request?.ip || "unknown");
  api.refreshToken.setMetadata("initial_asn", event.request?.asn?.value || "unknown");
  api.refreshToken.setMetadata("initial_country", event.request?.geoip?.country_code || "unknown");
  api.refreshToken.setMetadata("initial_user_agent", event.request?.user_agent || "unknown");
};
```

<div id="validate-device-information-during-refresh-token-exchange">
  ### Validar la información del dispositivo al intercambiar el Token de actualización
</div>

```javascript lines theme={null}
exports.onExecutePostLogin = async (event, api) => {
  // Solo validar si se trata de un intercambio de token de actualización
  if (!event.refresh_token) return;

  // Leer la información original del dispositivo
  const initialCountry = event.refresh_token.metadata?.initial_country;
  const currentCountry = event.request?.geoip?.country_code;

  // Ejemplo: Detectar cambio de país y tomar acción
  if (initialCountry && currentCountry && initialCountry !== currentCountry) {
    console.log(`Country changed from ${initialCountry} to ${currentCountry}`);
    
    // Opción 1: Revocar el token de actualización por actividad sospechosa
    // api.refreshToken.revoke("Suspicious country change detected");
    
    // Opción 2: Actualizar los metadatos para registrar el cambio
    api.refreshToken.setMetadata("country_changed", "true");
    api.refreshToken.setMetadata("last_country", currentCountry);
  }
};
```

<div id="error-handling">
  ## Manejo de errores
</div>

Puede revisar los eventos de registro de metadatos del Token de actualización navegando a [Dashboard > Monitoring > Logs](https://manage.auth0.com/#/logs) o recuperar los registros mediante el endpoint de [registros de Management API](/es/docs/api/management/v2/logs/get-logs).

* Si se produce un error al agregar o actualizar los metadatos del Token de actualización con Actions, la transacción de autenticación falla y se devuelve un error a la URL de devolución de llamada.

Se registra un código de evento de error `f` con el error correspondiente:

```json lines theme={null}
{
  "error": "access_denied",
  "error_description": "Failed to set refresh token metadata: Invalid metadata: Metadata keys may only include letters, numbers, underscores, or hyphens",
  "state": "my-custom-state"
}
```

* Si se produce un error al administrar los metadatos del Token de actualización mediante la Management API de Auth0, la API responde con un error `HTTP status: 400` y el mensaje correspondiente:

```json lines theme={null}
{
  "statusCode": 400,
  "message": "Metadata must not exceed 25 entries. Each key and value must be ≤ 255 characters."
}
```

<div id="learn-more">
  ## Más información
</div>

* [Metadatos del token de actualización](/es/docs/secure/tokens/refresh-tokens/refresh-token-metadata)
* [Tokens de actualización con Actions](/es/docs/secure/tokens/refresh-tokens/manage-refresh-tokens-actions)
* [Tokens de actualización](/es/docs/secure/tokens/refresh-tokens)
* [Objeto de evento Post-Login](/es/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-event-object)
* [Objeto de API Post-Login](/es/docs/customize/actions/explore-triggers/signup-and-login-triggers/login-trigger/post-login-api-object)