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

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

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

Abre Developer apps

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

Inicia una nueva aplicación

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

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.

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.

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.

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.

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:

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

Si la persona no ha iniciado sesión, Flowella le pide que lo haga primero.
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.
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.
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.

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:

{
  "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:

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.

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:

Ve a Settings y selecciona Installed apps en el grupo Developer.
Selecciona Revoke en la fila de la aplicación.
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.

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.

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

Autenticación, scopes, límites de velocidad y errores.

Developer hub

Solicitudes de API recientes, guías de inicio rápido y el sandbox de la API.

Claves de API

Acceso más sencillo para tus propios scripts e integraciones.

Referencia de webhooks

Reacciona a eventos en las organizaciones que instalan tu aplicación.

Primeros pasos

Esenciales

Uso de la aplicación

Configuración

Configuración de Meta y WhatsApp

Integración con HubSpot

Flujos y campañas

Referencia de API

Solución de problemas

Registro de cambios

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

Cómo funciona

Antes de empezar

Registrar una aplicación

Guiar a un cliente por la autorización

Qué ve el cliente

Intercambiar el código por tokens

Llamar a la API

Actualizar un token de acceso

Acceder a tu propia organización

Revocar o inspeccionar un token

Revisar y revocar aplicaciones instaladas

Eliminar una aplicación

Solución de problemas

Relacionado

Introducción a la API

Developer hub

Claves de API

Referencia de webhooks

​Cómo funciona

​Antes de empezar

​Registrar una aplicación

​Guiar a un cliente por la autorización

​Qué ve el cliente

​Intercambiar el código por tokens

​Llamar a la API

​Actualizar un token de acceso

​Acceder a tu propia organización

​Revocar o inspeccionar un token

​Revisar y revocar aplicaciones instaladas

​Eliminar una aplicación

​Solución de problemas

​Relacionado

Introducción a la API

Developer hub

Claves de API

Referencia de webhooks

Cómo funciona

Antes de empezar

Registrar una aplicación

Guiar a un cliente por la autorización

Qué ve el cliente

Intercambiar el código por tokens

Llamar a la API

Actualizar un token de acceso

Acceder a tu propia organización

Revocar o inspeccionar un token

Revisar y revocar aplicaciones instaladas

Eliminar una aplicación

Solución de problemas

Relacionado