Flujo OAuth (Connect Apps)

Cómo tu app obtiene credenciales para operar en nombre de un workspace de IxiChat. Patrón estándar OAuth 2.0 código de autorización: el dueño del workspace autoriza desde una pantalla de consent, vos recibís un code, lo intercambias por un api_key.

Antes de empezar

Necesitás una Connect App registrada. Hay dos formas:

• Self-service: registrá tu app vos mismo en /app/developers/new. Queda en draft hasta que un admin de IxiChat la apruebe.
• Curada por admin: si sos partner formal, contactanos en ventas@ixichat.com y la registramos por vos directo en activo.

El flujo paso a paso

1. Redirigí al usuario a la pantalla de consent

Desde tu app, abrí la URL https://ixichat.com/connect/<tu-slug> en una nueva pestaña, popup o redirect full-page. Pasale dos query params obligatorios:

https://ixichat.com/connect/mi-app?redirect_uri=https%3A%2F%2Fmiapp.com%2Fixichat%2Fcallback&state=abc123xyz

2. El usuario autoriza

IxiChat le muestra una pantalla de consent con el nombre de tu app, los scopes que pediste, y un botón "Autorizar". El usuario elige cuál de sus workspaces te conecta (si tiene varios) y un canal default (típicamente WhatsApp).

3. Recibís el code en tu redirect_uri

IxiChat redirige al usuario a tu redirect_uri agregando dos params:

GET https://miapp.com/ixichat/callback?code=cnct_<48-chars>&state=abc123xyz

Verificá state contra el que generaste en el paso 1. Si no matchea: rechazá la request (probable CSRF).

4. Intercambiá el code por credenciales

Desde tu backend (NO desde el browser — el client_secret no puede viajar al cliente):

curl -X POST https://ixichat.com/api/connect/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "code": "cnct_<el-code-recibido>",
    "redirect_uri": "https://miapp.com/ixichat/callback",
    "client_id": "cid_<tu-client-id>",
    "client_secret": "ixc_sec_<tu-secret>"
  }'

Respuesta:

{
  "tenant_id": "...",
  "tenant_slug": "ganando",
  "tenant_name": "Ganando",
  "api_key": "ixc_live_<...>",
  "webhook_url": "https://miapp.com/api/webhooks/ixichat",
  "webhook_secret": "whsec_<...>",
  "default_channel": {
    "id": "...",
    "name": "Soporte Ganando",
    "phone": "18091234567",
    "type": "whatsapp"
  },
  "scopes": ["read", "messages.send", "contacts.write", "conversations.write"]
}

Refresh y revoke

Rotar el api_key (refresh)

Los api_key tienen TTL de 1 año. Para rotarlo antes (mejor práctica: hacerlo cada 60-90 días):

curl -X POST https://ixichat.com/api/connect/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "cid_...",
    "client_secret": "ixc_sec_...",
    "api_key": "ixc_live_<vigente>"
  }'

Respuesta: { api_key: "<nuevo>", expires_at }. El api_key viejo queda revocado al instante.

Uninstall (revoke)

Si tu app necesita "desconectarse" de un workspace (el usuario canceló su subscripción a tu app, etc.):

curl -X POST https://ixichat.com/api/connect/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "cid_...",
    "client_secret": "ixc_sec_...",
    "api_key": "ixc_live_<a-revocar>"
  }'

Idempotente. Devuelve { revoked: true, already?: true }.

Scopes

Errores comunes