> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Registra una aplicación de partner con OAuth y gestiona las aplicaciones instaladas

> Registra una aplicación OAuth, guía a los clientes por la pantalla de consentimiento de Flowella, intercambia códigos por tokens y revisa o revoca las aplicaciones instaladas en tu organización.

Una aplicación OAuth permite que otras organizaciones de Flowella conecten tu producto a su cuenta sin compartir claves de API. Cada organización aprueba tu aplicación en una pantalla de consentimiento y puede revocarla en cualquier momento. Esta página muestra a los partners cómo registrar una aplicación y usar OAuth, y a los clientes cómo revisar y revocar las aplicaciones que han instalado.

Para tus propios scripts e integraciones, una [clave de API](https://knowledge.flowella.io/es/settings/api-keys.md) es más sencilla.

## Cómo funciona

Flowella admite tres tipos de concesión OAuth: código de autorización con PKCE para las organizaciones de los clientes, credenciales de cliente para tu propia organización y tokens de actualización. La secuencia muestra cómo un cliente instala tu aplicación con la concesión de código de autorización.

```mermaid theme={null}
sequenceDiagram
    participant Admin as Administrador del cliente
    participant App as Tu aplicación
    participant Flowella
    App->>Admin: Redirige a la URL de autorización de Flowella
    Admin->>Flowella: Abre la URL de autorización
    Flowella->>Admin: Muestra la pantalla de consentimiento
    Admin->>Flowella: Selecciona Allow access
    Flowella->>App: Redirige de vuelta con un código
    App->>Flowella: Intercambia el código y el verificador
    Flowella->>App: Tokens de acceso y de actualización
    App->>Flowella: Llama a la API con el token de acceso
```

## Antes de empezar

* Necesitas el rol **Owner** o **Admin** en la organización que será propietaria de la aplicación. Los demás roles pueden ver **Developer apps** en el menú, pero la lista no se carga para ellos.
* Tu aplicación necesita una dirección de retorno (redirect URI) que pueda recibir el código de autorización.
* Tu aplicación debe enviar un valor `state` y un `code_challenge` PKCE generado con `S256` en cada solicitud de autorización.

## Registrar una aplicación

**1. Abre Developer apps**

Ve a **Settings** y selecciona **Developer apps** en el grupo **Developer**.

**2. Inicia una nueva aplicación**

Selecciona **Create app**. Se abre el cuadro de diálogo **Create developer app**.

**3. Ponle nombre a la aplicación**

En **App name**, introduce el nombre con el que los clientes conocen tu producto, de hasta 120 caracteres, por ejemplo `Acme CRM connector`.

**4. Añade los redirect URI**

En **Redirect URIs**, introduce cada dirección de retorno en su propia línea, hasta 20. Durante la autorización, el `redirect_uri` que envía tu aplicación debe coincidir exactamente con uno de ellos.

**5. Elige los scopes**

En **Scopes**, los scopes de lectura vienen marcados. Marca cualquier otro scope que necesite tu aplicación y desmarca los que no necesite. Estos son los máximos que tu aplicación podrá solicitar. Consulta [Scopes](https://knowledge.flowella.io/es/api-reference/introduction.md#scopes).

**6. Crea la aplicación y copia el secreto**

Selecciona **Create app**. El cuadro de diálogo **Save your client secret** muestra el client secret, que empieza por `flc_`. Selecciona **Copy**, guarda el secreto en tu servidor y después selecciona **Done**.

> [!WARNING]
>
> Flowella solo muestra el client secret una vez y no puedes restablecerlo. Si lo pierdes, tendrás que eliminar la aplicación y registrar una nueva, y todas las organizaciones que usan tu aplicación deberán aprobar la nueva.

No puedes cambiar el nombre, los redirect URI ni los scopes de una aplicación después de crearla. Para cambiarlos, registra una aplicación nueva.

La lista **Developer apps** muestra el **Name**, el **Client ID** (empieza por `floa_`), los **Redirect URIs** y la fecha **Created** de cada aplicación, con un botón **Delete** en **Actions**.

## Guiar a un cliente por la autorización

Envía el navegador del cliente al endpoint de autorización del host de la aplicación de Flowella:

```text theme={null}
https://app.flowella.io/api/oauth/authorize?response_type=code&client_id=floa_xxxx&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=messages%3Aread%20contacts%3Aread&state=RANDOM_STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256
```

| Parámetro | Obligatorio | Valor |
| - | - | - |
| `response_type` | Sí | `code` |
| `client_id` | Sí | El client ID de tu aplicación. |
| `redirect_uri` | Sí | Uno de los redirect URI registrados de la aplicación, exactamente igual. |
| `state` | Sí | Un valor aleatorio que tu aplicación comprueba cuando el cliente vuelve. |
| `code_challenge` | Sí | El hash SHA-256, codificado en base64url, de un `code_verifier` aleatorio que conserva tu aplicación. |
| `code_challenge_method` | No | `S256`, el único método admitido y el predeterminado. |
| `scope` | No | Scopes separados por espacios, todos dentro de los scopes de la aplicación. Si no se indica, la aplicación solo obtiene los scopes de lectura que tiene permitidos. |
| `publicOrgId` | No | El número de organización de seis dígitos de la dirección web de Flowella del cliente. Si no se indica, Flowella usa la organización en la que la persona está trabajando en ese momento. |

Si la solicitud no es válida, Flowella muestra un error en lugar de la pantalla de consentimiento y no redirige. Esto ocurre, por ejemplo, cuando el `redirect_uri` no coincide o un scope no está permitido.

### Qué ve el cliente

1. Si la persona no ha iniciado sesión, Flowella le pide que lo haga primero.
2. La persona debe ser **Owner** o **Admin** de la organización. Cualquier otra persona ve el error `Owner or admin role required to authorize apps`.
3. La pantalla **Authorize app** muestra tu **Client ID:** y los **Requested scopes:**. Si tu aplicación no envió un `scope`, indica **This app will receive its default allowed scopes.**
4. La persona selecciona **Allow access** o **Deny**.

**Allow access** envía el navegador a tu `redirect_uri` con `code` y `state` en la cadena de consulta. El código es válido durante 10 minutos y solo funciona una vez. **Deny** envía el navegador a tu `redirect_uri` con `error=access_denied`, un `error_description` y tu `state`.

## Intercambiar el código por tokens

Tu servidor intercambia el código en el endpoint de tokens. Autentícate con tu client ID y tu secreto, ya sea con autenticación HTTP Basic o como `client_id` y `client_secret` en el cuerpo. El cuerpo puede estar codificado como formulario o en JSON.

```bash theme={null}
curl -X POST "https://app.flowella.io/api/oauth/token" \
  -u "$FLOWELLA_CLIENT_ID:$FLOWELLA_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri="https://example.com/oauth/callback" \
  -d code_verifier="$CODE_VERIFIER"
```

La respuesta contiene los tokens:

```json theme={null}
{
  "access_token": "fla_xxxxxxxxxxxxxxxx",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "flr_xxxxxxxxxxxxxxxx",
  "scope": "messages:read contacts:read"
}
```

| Token | Empieza por | Validez |
| - | - | - |
| Token de acceso | `fla_` | 1 hora |
| Token de actualización | `flr_` | 30 días, y solo hasta que se usa una vez |

El endpoint de tokens acepta 30 solicitudes por minuto por cada client ID y dirección IP. Por encima de ese límite, devuelve `429` con una cabecera `Retry-After`.

## Llamar a la API

Envía el token de acceso como bearer token, exactamente igual que una clave de API:

```http theme={null}
Authorization: Bearer fla_xxxxxxxxxxxxxxxx
```

El token solo funciona para la organización que lo aprobó y solo para los scopes concedidos. Una solicitud fuera de esos scopes devuelve `403 INSUFFICIENT_SCOPE`. Cada token de acceso tiene su propio límite de velocidad. Consulta la [introducción a la API](https://knowledge.flowella.io/es/api-reference/introduction.md).

> [!NOTE]
>
> `POST /v1/templates/send` solo acepta claves de API y rechaza los tokens de acceso OAuth con `401`.

### Actualizar un token de acceso

Antes de que caduque el token de acceso, solicita uno nuevo con `grant_type=refresh_token`, el `refresh_token` y la autenticación de tu cliente. La respuesta incluye un nuevo token de acceso y un nuevo token de actualización, y el token de actualización anterior deja de funcionar. Si alguien presenta un token de actualización que ya se había usado, Flowella revoca todos los tokens emitidos a partir de esa autorización y el cliente tiene que volver a aprobar tu aplicación.

### Acceder a tu propia organización

Para llamar a la API en nombre de la organización propietaria de la aplicación, usa `grant_type=client_credentials` con la autenticación de tu cliente y un `scope` opcional. Obtienes un token de acceso sin token de actualización. Después, tu aplicación aparece en **Installed apps** de tu propia organización.

### Revocar o inspeccionar un token

| Endpoint | Qué hace |
| - | - |
| `POST https://app.flowella.io/api/oauth/revoke` | Revoca el `token` que envías, junto con todos los tokens emitidos con él. |
| `POST https://app.flowella.io/api/oauth/introspect` | Indica si el `token` está `active`, con su `scope`, `client_id`, `organization_id` y hora de caducidad. |

Ambos endpoints necesitan la autenticación de tu cliente. El documento de descubrimiento en `https://app.flowella.io/.well-known/oauth-authorization-server` enumera todos los endpoints y las opciones admitidas.

## Revisar y revocar aplicaciones instaladas

Los clientes gestionan las aplicaciones que han aprobado en **Installed apps**. Necesitas el rol **Owner** o **Admin**. La lista muestra:

| Columna | Qué muestra |
| - | - |
| **App** | El nombre de la aplicación, con su client ID debajo. |
| **Scopes** | Los scopes concedidos a la aplicación. |
| **Installed** | Cuándo se aprobó la aplicación por primera vez. |
| **Actions** | **Revoke**, o una insignia **Revoked**. |

Para revocar una aplicación:

1. Ve a **Settings** y selecciona **Installed apps** en el grupo **Developer**.
2. Selecciona **Revoke** en la fila de la aplicación.
3. Confirma el aviso **Revoke this install? Existing tokens stop working.**

Los tokens de la aplicación dejan de funcionar al instante y no puede actualizarlos. La fila permanece en la lista con una insignia **Revoked**. Para volver a dar acceso a la aplicación, un Owner o Admin debe aprobarla de nuevo en la pantalla de consentimiento.

> [!NOTE]
>
> Revocar tu propia aplicación en tu propia organización no detiene la concesión de credenciales de cliente: la aplicación puede solicitar un nuevo token, lo que vuelve a activar la instalación. Para cortar por completo el acceso de tu propia aplicación, elimínala en **Developer apps**.

## Eliminar una aplicación

En **Developer apps**, selecciona **Delete** en la fila de la aplicación y confirma **Delete this app and its tokens?** Flowella elimina la aplicación, su instalación en todas las organizaciones que la aprobaron y todos sus tokens. Esta acción no se puede deshacer.

## Solución de problemas

> **Could not load developer apps o Could not load installed apps**
>
> Solo los Owners y Admins pueden ver estas pantallas. Pide a un Owner o Admin que gestione la aplicación por ti. Los roles no se pueden cambiar en la aplicación: consulta [Cambiar el rol de alguien](https://knowledge.flowella.io/es/settings/team.md#cambiar-el-rol-de-alguien).

> **El redirect URI no coincide**
>
> El `redirect_uri` de la solicitud debe coincidir exactamente con uno de los redirect URI registrados de la aplicación, incluidos el esquema, la ruta y cualquier barra final. Debes enviar el mismo valor de nuevo al intercambiar el código. No puedes editar los redirect URI de una aplicación, así que registra una aplicación nueva si necesitas uno distinto.

> **invalid\_scope**
>
> Un scope solicitado está mal escrito o no es uno de los scopes de la aplicación. Solicita solo los scopes que marcaste al registrar la aplicación.

> **Owner or admin role required to authorize apps**
>
> La persona que aprueba la aplicación no es Owner ni Admin de la organización. Pide a un Owner o Admin que complete la autorización.

> **El intercambio del código falla**
>
> Los mensajes `Authorization code expired` y `Authorization code already used` significan que tienes que iniciar la autorización de nuevo: los códigos duran 10 minutos y solo funcionan una vez. `PKCE verification failed` significa que el `code_verifier` no coincide con el `code_challenge` que enviaste.

## Relacionado

> **[Introducción a la API](https://knowledge.flowella.io/es/api-reference/introduction.md)**
>
> Autenticación, scopes, límites de velocidad y errores.

> **[Developer hub](https://knowledge.flowella.io/es/settings/developer-hub.md)**
>
> Solicitudes de API recientes, guías de inicio rápido y el sandbox de la API.

> **[Claves de API](https://knowledge.flowella.io/es/settings/api-keys.md)**
>
> Acceso más sencillo para tus propios scripts e integraciones.

> **[Referencia de webhooks](https://knowledge.flowella.io/es/api-reference/webhooks.md)**
>
> Reacciona a eventos en las organizaciones que instalan tu aplicación.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.