> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.es/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cómo usar OAuth | Guía rápida de inicio de OAuth

> Aprende a configurar OAuth para tu aplicación utilizando esta guía rápida y una aplicación Node.js de ejemplo.

'Aprende a configurar OAuth para tu aplicación utilizando esta guía rápida y una aplicación Node.js de ejemplo.';

<style>
  {`
    .github-link a div,
    .github-link a div p {
      display: inline;
      margin: 0;
      padding: 0;
    }
    .github-link {
      background-color: rgb(255, 255, 255);
      border-radius: 24px;
      box-shadow: rgba(0, 0, 0, 0.25) 0px 2px 4px 0px;
      padding: 5px;
      max-width: 247px;
      display: flex;
      align-items: center;
      margin-bottom: 20px;
    }
    .github-icon {
        display: inline;
        width: 24px;
        margin-right: 8px;
        flex-shrink: 0;
    }
    .table-key, .table-key div, .table-key p {
      margin: 0;
      font-size: 14px;
    }
    `}
</style>

## Antes de comenzar

Antes de comenzar a usar OAuth con HubSpot, necesitarás:

* [Una cuenta de desarrollador](https://app.hubspot.com/signup-hubspot/crm?intent=developer)
* [Una aplicación](/apps/legacy-apps/public-apps/overview) asociada con tu cuenta de desarrollador
* Una cuenta de HubSpot para instalar tu aplicación (puedes usar una cuenta existente o [crear una cuenta de prueba](/getting-started/account-types))

<Alert type="warning">
  Debes ser un [superadministrador](https://knowledge.hubspot.com/es/user-management/hubspot-user-permissions-guide#super-admin) para instalar una aplicación en una cuenta de HubSpot.
</Alert>

### Cómo funciona

HubSpot admite el [tipo de autorización con código en OAuth 2.0](https://developer.okta.com/blog/2018/04/10/oauth-authorization-code-grant-type), que puede dividirse en cuatro pasos básicos:

1. Tu aplicación abre una ventana del navegador para enviar al usuario al servidor de HubSpot OAuth 2.0
2. El usuario revisa los permisos solicitados y otorga el acceso a la aplicación
3. El usuario es redirigido a la aplicación con un código de autorización en la cadena de consulta
4. La aplicación envía una solicitud al servidor de OAuth 2.0 para intercambiar el código de autorización por un token de acceso

### En esta guía:

* [Aplicación de inicio rápido](#quickstart-app): Es una aplicación de demostración en Node.js que se autentica con el servidor OAuth 2.0 de HubSpot
* [Obtener tokens de OAuth 2.0](#getting-oauth-tokens): Cómo autorizar tu aplicación con los usuarios
* [Usar los tokens de OAuth 2.0](#using-oauth-tokens): Cómo realizar consultas con un token
* [Actualización de tokens de OAuth 2.0](#refreshing-oauth-tokens): Cómo usar el token de actualización proporcionado por HubSpot

<Alert type="info">
  Todos los ejemplos de código de esta guía están escritos en JavaScript (Node.js)
</Alert>

## Aplicación de inicio rápido

Si es la primera vez que usas la autenticación OAuth con las API de HubSpot, te recomendamos que consultes la [Aplicación de inicio rápido de OAuth 2.0](https://github.com/HubSpot/oauth-quickstart-nodejs), escrita en Node.js. Esta aplicación está diseñada para que puedas comenzar a usar OAuth 2.0 lo más rápido posible mediante la demostración de todos los pasos que se detallan a continuación en la sección [Obtener tokens de OAuth 2.0](#getting-oauth-tokens).

<div className="github-link">
  <img className="github-icon" src="https://developers.hubspot.com/hubfs/Knowledge_Base_2023-24-25/uie-icons/github.png" alt="GitHub icon" />

  <a href="https://github.com/HubSpot/oauth-quickstart-nodejs" target="_blank">
    Obtener la aplicación de inicio rápido
  </a>
</div>

## Obtener tokens de OAuth 2.0

### 1. Crea la URL de autorización y dirige al usuario al servidor OAuth 2.0 de HubSpot

Al enviar un usuario al servidor OAuth 2.0 de HubSpot, el primer paso es crear la URL de autorización. Esto identificará tu aplicación y definirá los recursos (los permisos) a los que solicita acceso en nombre del usuario. Los parámetros de consulta que puedes pasar como parte de una URL de autorización se muestran a continuación. Para obtener información más detallada sobre este paso, lee el [documento de referencia](/apps/legacy-apps/authentication/working-with-oauth).

<p className="table-key">
  Los campos marcados con <span style={{ color: 'red' }}>\*</span> son
  obligatorios.
</p>

| Parámetro                                           | Descripción                                                                                                                                                              | Ejemplo                                 |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `client_id`<span style={{color:"red"}}>\*</span>    | El ID del cliente identifica tu aplicación. Encuéntralo en la página de configuración de tu aplicación.                                                                  | `7fff1e36-2d40-4ae1-bbb1-5266d59564fb`  |
| `scope`<span style={{color:"red"}}>\*</span>        | Los [permisos](/apps/legacy-apps/authentication/scopes#list-of-available-scopes) que tu aplicación solicita, separados por espacios codificados de URL (`%20`).          | `oauth%20crm.objects.contacts.read`     |
| `redirect_uri`<span style={{color:"red"}}>\*</span> | La URL a la que el usuario será redirigido después de autorizar a tu aplicación para los permisos solicitados. **Para aplicaciones en producción, se requiere `https`.** | `https://www.example.com/auth-callback` |
| `optional_scope`                                    | Los permisos que son opcionales para tu aplicación y se eliminarán si el portal de HubSpot seleccionado no tiene acceso a esos productos                                 | `automation`                            |
| `state`                                             | Un valor de cadena que se puede usar para mantener el estado del usuario cuando se redirecciona de regreso a tu aplicación.                                              | `WeHH_yy2irpl8UYAvv-my`                 |

Una vez que hayas creado tu URL, envía al usuario a OAuth 2.0 para iniciar el proceso.

Los bloques de código que aparecen a continuación ofrecen ejemplos de utilización de distintos tipos de redireccionamiento:

**Usando una redirección del lado del servidor:**

```js theme={null}
// Build the auth URL
const authUrl =
  "https://app.hubspot.com/oauth/authorize" +
  `?client_id=${encodeURIComponent(CLIENT_ID)}` +
  `&scope=${encodeURIComponent(SCOPES)}` +
  `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
  `&state=${encodeURIComponent(STATE)}`;

// Redirect the user
return res.redirect(authUrl);
```

**Usando un enlace HTML:**

```html theme={null}
<a
  href="https://app.hubspot.com/oauth/authorize?scope=contacts%20social&redirect_uri=https://www.example.com/auth-callback&client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&state=xxxxxxxx"
  >Install</a
>
```

**Codificación de un estado adicional de redirección del usuario**

Algunas aplicaciones pueden necesitar redirigir al usuario a diferentes ubicaciones. Por ejemplo, es posible que una aplicación desee redirigir a los usuarios a diferentes subdominios de su integración (por ejemplo, `userA.integration.com` y `userB.integration.com`). Para ello, utiliza el parámetro `state` para codificar más información sobre el estado del usuario:

1\. Genera y almacena un valor "nonce" para el parámetro de estado.

2\. Almacena el estado del usuario en un almacén de datos local utilizando el "nonce" como su clave.

3\. Incluye el valor "nonce" como el parámetro de estado en la URL de autorización.

4\. Cuando el usuario se autentica y es redirigido a tu URL de redirección, valida el parámetro de estado y úsalo como la clave para recuperar el estado de usuario que estaba almacenado.

5\. Desde allí, redirige al usuario según sea necesario (por ejemplo, redirige de nuevo a una URL específica del usuario).

### 2. HubSpot solicita al usuario su consentimiento

HubSpot muestra una ventana de consentimiento al usuario que muestra el nombre de tu aplicación y una breve descripción de los servicios de la API de HubSpot a los que solicita permiso para acceder. El usuario puede otorgar acceso a tu aplicación.

![Ejemplo de ventana de instalación](https://www.hubspot.es/hubfs/Knowledge_Base_2023/%5BExample%5D%20Install%20Screen.png)

**Nota:** El usuario que instala la aplicación debe tener acceso a todos los permisos solicitados. Si no tienen el acceso requerido, la instalación fallará y serán dirigidos a una página de error. Si un usuario ve esta página de error de permisos, necesitará que un superadministrador instale la aplicación.

Tu aplicación no hace nada en esta etapa. Una vez que se otorga el acceso, el servidor de OAuth 2.0 de HubSpot enviará una solicitud a la URI de devolución de llamada definida en la URL de autorización.

### 3. Manejar la respuesta del servidor OAuth

Cuando el usuario haya completado la solicitud de consentimiento del paso 2, el servidor OAuth 2.0 envía una solicitud `GET` al URI de redireccionamiento especificado en tu URL de autenticación. Si no hay problemas y el usuario aprueba la solicitud de acceso, la solicitud al URI de redireccionamiento se devolverá con un parámetro de consulta de `code` adjunto. Si el usuario no otorga el acceso, no se enviará ninguna solicitud.

**Ejemplo:**

```js theme={null}
app.get("/oauth-callback", async (req, res) => {
  if (req.query.code) {
    // Handle the received code
  }
});
```

### 4. Intercambiar el código de autorización por tokens

Después de que tu aplicación reciba un código de autorización del servidor OAuth 2.0, puede intercambiar ese código por un token de acceso y actualización al enviar una solicitud `POST` codificada en formato de formulario URL a `https://api.hubapi.com/oauth/v1/token` con los valores que se muestran a continuación. Para obtener información más detallada sobre este paso, puedes leer este [documento de referencia](/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth).

| Parámetro       | Descripción                                                                            | Ejemplo                                 |
| --------------- | -------------------------------------------------------------------------------------- | --------------------------------------- |
| `grant_type`    | Debe ser `authorization_code`                                                          | `authorization_code`                    |
| `client_id`     | ID de cliente de tu aplicación                                                         | `7fff1e36-2d40-4ae1-bbb1-5266d59564fb`  |
| `client_secret` | La clave de cliente de tu aplicación                                                   | `7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d`  |
| `redirect_uri`  | El URI de redireccionamiento desde el momento en que el usuario autorizó tu aplicación | `https://www.example.com/auth-callback` |
| `code`          | El código de autorización recibido del servidor OAuth 2.0                              | `5771f587-2fe7-40e8-8784-042fb4bc2c31`  |

**Ejemplo:**

```js theme={null}
const formData = {
  grant_type: 'authorization_code',
  client_id: CLIENT_ID,
  client_secret: CLIENT_SECRET,
  redirect_uri: REDIRECT_URI,
  code: req.query.code
};

request.post('https://api.hubapi.com/oauth/v1/token', { form: formData }, (err, data) => {
  // Handle the returned tokens
}
```

El cuerpo de la respuesta del token serán datos JSON con la estructura:

```json theme={null}
{
  "refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1",
  "access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I",
  "expires_in": 1800
}
```

<Alert type="warning" titleText="Nota:">
  El token de acceso vencerá después de la cantidad de segundos indicada en el campo `expires_in` de la respuesta, actualmente, 30 minutos. Para más detalles sobre cómo obtener un nuevo token de acceso, consulta la sección [Actualizar tokens OAuth](#refreshing-oauth-tokens) más abajo.
</Alert>

## Uso de tokens de OAuth 2.0

Una vez que se complete el proceso de autorización, tu aplicación está autorizada para realizar solicitudes en nombre del usuario. Para ello, proporciona el token como token de portador en el encabezado HTTP `Authorization`. Los detalles específicos se pueden encontrar en el [documento de referencia](/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth).

**Ejemplo:**

```js theme={null}
request.get(
  "https://api.hubapi.com/contacts/v1/lists/all/contacts/all?count=1",
  {
    headers: {
      Authorization: `Bearer ${ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
  },
  (err, data) => {
    // Handle the API response
  }
);
```

<Alert type="warning" titleText="Nota:">
  Los tokens de acceso reflejan los permisos solicitados desde la aplicación y no reflejan los permisos o limitaciones de lo que un usuario puede hacer en su cuenta de HubSpot. Por ejemplo, si un usuario tiene permisos para ver solo los contactos de su propiedad, pero autoriza una solicitud para el permiso `crm.objects.contacts.read`, el token de acceso resultante puede ver todos los contactos de la cuenta y no solo los que son propiedad del usuario que autoriza.
</Alert>

## Actualización de tokens de OAuth 2.0

Los tokens de acceso de OAuth caducan periódicamente. Así se limita el acceso de los atacantes a un corto plazo si se produce una vulneración. La vida útil del token en segundos se especifica en el campo `expires_in` cuando se intercambia un código de autorización por un token de acceso.

Tu aplicación puede intercambiar el token de actualización recibido por un nuevo token de acceso enviando una solicitud `POST` codificada en formato de formulario URL a `https://api.hubapi.com/oauth/v1/token` con los siguientes valores. Para obtener información más detallada sobre este paso, consulta el [documento de referencia](/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth).

| Parámetro       | Descripción                                                                            | Ejemplo                                 |
| --------------- | -------------------------------------------------------------------------------------- | --------------------------------------- |
| `grant_type`    | Debe ser `refresh_token`                                                               | `refresh_token`                         |
| `client_id`     | ID de cliente de tu aplicación                                                         | `7fff1e36-2d40-4ae1-bbb1-5266d59564fb`  |
| `client_secret` | La clave de cliente de tu aplicación                                                   | `7c3ce02c-0f0c-4c9f-9700-92440c9bdf2d`  |
| `redirect_uri`  | El URI de redireccionamiento desde el momento en que el usuario autorizó tu aplicación | `https://www.example.com/auth-callback` |
| `refresh_token` | El token de actualización recibido cuando el usuario autorizó a tu aplicación          | `b9443019-30fe-4df1-a67e-3d75cbd0f726`  |

**Ejemplo:**

```js theme={null}
const formData = {
  grant_type: 'refresh_token',
  client_id: CLIENT_ID,
  client_secret: CLIENT_SECRET,
  redirect_uri: REDIRECT_URI,
  refresh_token: REFRESH_TOKEN
};

request.post('https://api.hubapi.com/oauth/v1/token', { form: formData }, (err, data) => {
  // Handle the returned tokens
}
```

El cuerpo de la respuesta del token serán datos JSON con la estructura:

```json theme={null}
{
  "refresh_token": "6f18f21e-a743-4509-b7fd-1a5e632fffa1",
  "access_token": "CN2zlYnmLBICAQIYgZXFLyCWp1Yoy_9GMhkAgddk-zDc-H_rOad1X2s6Qv3fmG1spSY0Og0ACgJBAAADAIADAAABQhkAgddk-03q2qdkwdXbYWCoB9g3LA97OJ9I",
  "expires_in": 1800
}
```

El nuevo token de acceso puede usarse para hacer llamadas en nombre del usuario. Cuando el nuevo token caduque, puedes seguir los mismos pasos nuevamente para generar uno nuevo.

## Artículos relacionados

[Métodos de autenticación en HubSpot](/apps/developer-platform/build-apps/authentication/overview)

[Cómo usar OAuth](/apps/legacy-apps/authentication/working-with-oauth)

[Administrar tokens](/apps/developer-platform/build-apps/authentication/oauth/working-with-oauth)