OAuth 2.0 para aplicaciones

OAuth 2.0 permite que una aplicación acceda a Planfix en nombre de un usuario sin solicitar ni almacenar la contraseña del usuario.

Planfix utiliza el flujo de Authorization Code con PKCE S256 obligatorio. OAuth puede usarse para conectarse al REST API o al servidor MCP de Planfix.

Si quieres conectar un cliente de IA ya hecho, comienza por Planfix MCP. Si gestionas el acceso en tu cuenta, consulta Aplicaciones OAuth y MCP en una cuenta. Los socios y desarrolladores de integraciones multi-cuenta deben ver Aplicaciones OAuth para socios.

Opciones de registro de la aplicación

Opción	Cuándo usarla	Dónde funciona
Aplicación propiedad de la cuenta	La integración está pensada para una sola cuenta y el cliente necesita un client_id predefinido.	Solo en la cuenta que la posee.
Aplicación propiedad del socio	La misma aplicación debe conectarse a múltiples cuentas de clientes.	En las cuentas donde lo permita la política de seguridad o un administrador.
Registro automático de cliente MCP	El cliente MCP soporta un Client ID Metadata Document (CIMD) o Dynamic Client Registration (DCR).	El registro por sí solo no otorga acceso a la cuenta. La aplicación aún debe ser permitida en la cuenta seleccionada.

CIMD y DCR están disponibles solo para conexiones MCP. Para la REST API, usa una aplicación propiedad de la cuenta o propiedad del socio.

Endpoints de OAuth

Las nuevas integraciones deben usar los endpoints globales. El nombre de la cuenta no se incluye en estas URLs: el usuario selecciona una cuenta durante la autorización.

Propósito	Dirección
Issuer	https://auth.planfix.com
Authorization	https://auth.planfix.com/oauth/authorize
Token	https://auth.planfix.com/oauth/token
Información del usuario	https://auth.planfix.com/oauth/userinfo
Revocación de token	https://auth.planfix.com/oauth/revoke
Registro dinámico de cliente MCP	https://auth.planfix.com/oauth/register

Los metadatos del servidor de autorización están disponibles en los endpoints estándar:

https://auth.planfix.com/.well-known/oauth-authorization-server
https://auth.planfix.com/.well-known/openid-configuration

URIs de redirección

Debes registrar una URI de redirección en la configuración de la aplicación. El valor enviado en la solicitud de autorización debe coincidir con una URI registrada.

Se permiten las siguientes:

• URLs https;
• URLs http solo para hosts loopback, como localhost o 127.0.0.1.

El puerto puede ser dinámico para una URI loopback, pero su esquema, host, ruta y query deben coincidir. No se permiten fragmentos en la URL ni información de usuario en la URL.

Niveles de acceso

Una aplicación recibe únicamente los niveles de acceso, o scopes, que se permitieron de antemano. Consulta Niveles de acceso de la REST API para la lista completa.

El conjunto solicitado debe ser un subconjunto de los scopes registrados para la aplicación. Los scopes de la aplicación no extienden los permisos del usuario en Planfix: la aplicación solo puede acceder a los datos disponibles para el Empleado que la conectó.

Las aplicaciones gestionadas también reciben los scopes de servicio userinfo, openid y email.

Autorización del usuario

Genera un code_verifier y su representación SHA-256, code_challenge, y luego abre el endpoint de autorización en un navegador.

Ejemplo para la REST API:

GET https://auth.planfix.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
    &response_type=code
    &scope=openid%20email%20task_readonly
    &state=RANDOM_STATE
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

Para MCP, añade el parámetro resource con la URL exacta del servidor MCP:

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp

Parámetro	Descripción
client_id	El identificador de una aplicación registrada. Para CIMD, este es el URL del documento de metadatos del cliente.
redirect_uri	Una de las URIs de redirección permitidas.
response_type	Debe ser code.
scope	Los permisos requeridos separados por espacios. Este parámetro es obligatorio para la REST API. Un cliente MCP puede omitirlo, en cuyo caso se usan los scopes permitidos para la aplicación.
state	Un valor aleatorio que protege la solicitud de sustituciones. La aplicación debe validarlo después de la redirección.
code_challenge	Base64url sin padding del hash SHA-256 de code_verifier.
code_challenge_method	Solo se admite S256.
resource	Para MCP, la URL exacta https://mcp.planfix.com/mcp. No envíes este parámetro para la REST API.

El usuario selecciona una cuenta, inicia sesión y revisa los permisos solicitados. Una aplicación propiedad de la cuenta abre directamente la cuenta propietaria. Si la política de seguridad requiere aprobación administrativa, Planfix mostrará el paso correspondiente. Un administrador puede aprobar la aplicación y conectarla en una sola acción.

Tras una autorización exitosa, Planfix redirige el navegador a redirect_uri:

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com

Un código de autorización es de un solo uso y permanece válido durante 10 minutos.

Obtención de tokens

Envía una petición POST a /oauth/token usando application/x-www-form-urlencoded:

grant_type=authorization_code
&client_id=CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&code_verifier=CODE_VERIFIER

Para MCP, repite el parámetro resource con el mismo valor usado en la solicitud de autorización.

Un cliente público envía la solicitud sin secreto. Un cliente confidencial también se autentica usando client_secret_basic o los parámetros client_id y client_secret en el cuerpo de la solicitud.

Ejemplo de respuesta:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email task_readonly"
}

Para la REST API, la respuesta también contiene account_name, account_domain y account_url. Guarda estos valores y usa la URL de la cuenta seleccionada para las solicitudes a la REST API.

Un access token es válido por 24 horas. Está vinculado al usuario, cuenta, aplicación, scopes y resource. Un token emitido para MCP no puede usarse directamente con la REST API, y un token de la REST API no puede usarse con MCP.

Uso de un token con la REST API

Envía el token en el encabezado Authorization:

GET https://account.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

Usa la URL de cuenta devuelta cuando se intercambió el código de autorización por tokens. Solo están disponibles los métodos cubiertos por los scopes otorgados. Los tokens OAuth están sujetos al plan de la cuenta y a los límites de la REST API estándar.

Información del usuario

La solicitud userinfo requiere el scope openid:

GET https://auth.planfix.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Ejemplo de respuesta cuando está presente el scope email:

{
  "sub": "123:user:456",
  "email": "user@example.com",
  "email_verified": true
}

La autorización global de OAuth está disponible para los empleados de la cuenta. Planfix no emite un id_token; solicita los datos del usuario mediante userinfo en su lugar.

Refresco de tokens

POST https://auth.planfix.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=CLIENT_ID
&refresh_token=REFRESH_TOKEN

Para MCP, envía el mismo resource nuevamente. Un cliente confidencial debe autenticarse usando su secreto.

Planfix devuelve un nuevo access token y un nuevo refresh token. El refresh token anterior queda inválido inmediatamente, por lo que la aplicación debe reemplazar el valor almacenado de forma atómica.

Revocación de un token

Un cliente puede revocar un refresh token mediante /oauth/revoke:

POST https://auth.planfix.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Un usuario también puede eliminar una conexión desde la sección de Gestión de sesiones de su ficha de usuario. Un administrador puede revocar la aprobación de una aplicación de terceros para toda la cuenta. Ver Aplicaciones OAuth y MCP en una cuenta.

Compatibilidad con integraciones existentes

Los endpoints tenant como https://account.planfix.com/api/v2/oauth/authorize, /token y /userinfo siguen funcionando para integraciones existentes vinculadas a una cuenta específica.

Usa los endpoints globales para las nuevas integraciones. Soportan descubrimiento de metadatos estándar, selección de cuenta y MCP. No mezcles endpoints globales y tenant dentro de una misma sesión OAuth.

Recomendaciones de seguridad

• Usa siempre PKCE S256 y valida state.
• Usa un cliente público sin secreto para aplicaciones móviles, de escritorio y en navegador.
• Usa un cliente confidencial solo cuando el secreto pueda almacenarse de forma segura en un servidor.
• Solicita el conjunto mínimo de scopes requeridos.
• No escribas access tokens, refresh tokens, códigos de autorización, code_verifier o secretos de cliente en los logs.
• Almacena refresh tokens y secretos de cliente en almacenamiento cifrado.
• Valida iss en la respuesta y acepta solo el issuer esperado de Planfix.

Errores posibles

Error	Causa
invalid_client	El cliente es desconocido o está deshabilitado, el secreto del cliente es incorrecto, o la aplicación no está disponible en la cuenta seleccionada.
invalid_grant	El código de autorización o el refresh token es inválido, expirado, ya usado, o no coincide con el cliente, la URI de redirección, los datos PKCE, o el resource.
invalid_scope	La solicitud contiene un scope que no está permitido para la aplicación.
invalid_target	El resource no es compatible o cambió entre solicitudes.
access_denied	El usuario rechazó la conexión o la política de la cuenta no permite la aplicación.
HTTP 401, invalid_token	El access token es desconocido, expirado o revocado.
HTTP 403, insufficient_scope	El token no contiene el scope requerido para la operación.

Ir a

• Planfix MCP
• Aplicaciones OAuth y MCP en una cuenta
• Aplicaciones OAuth para socios
• REST API
• REST API Authorization
• REST API: Access Levels List – scope