Gestion de API Keys

Las API keys permiten que tus integraciones se autentiquen con SalesOS. Puedes crear y gestionar claves de dos formas:

Desde el Dashboard

Interfaz visual — ideal para la mayoria de los usuarios

Via API

Programatico — para automatizacion y CI/CD

La gestion de API keys requiere la capability admin.integrations. Los owners y admins del tenant la tienen por defecto.

Desde el Dashboard

La forma mas sencilla de crear una API key es a traves del Dashboard de SalesOS.

Abre el Dashboard

Ve a dashboard.play2sell.com e inicia sesion con tu cuenta de administrador.

Navega a API Keys

Ve a Integraciones > API Keys en el menu lateral.

Crea una nueva clave

Haz clic en Crear API Key y completa:

Nombre — Un nombre descriptivo (ej.: “Sincronizacion CRM Nocturna”, “Formularios del Sitio”)
Alcance — Selecciona default:sync para integraciones estandar
Limite de tasa — Solicitudes por hora (por defecto: 1.000)
Expiracion — Fecha de vencimiento opcional

Copia tu clave

Tu API key se mostrara una unica vez:

sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Copiala inmediatamente y guardala en un lugar seguro (ej.: variable de entorno, gestor de secretos).

La clave se muestra solo una vez despues de la creacion. Si la pierdes, deberas crear una nueva y revocar la anterior.

Gestionando claves en el Dashboard

Desde la misma pagina Integraciones > API Keys puedes:

Ver todas las claves activas, revocadas y expiradas
Revocar una clave — deja de funcionar inmediatamente
Eliminar una clave — la remueve permanentemente (prefiere revocar para mantener historial de auditoria)
Monitorear uso — ve conteo de solicitudes y fecha del ultimo uso

Via API

Para automatizacion, pipelines CI/CD o paneles admin personalizados, puedes gestionar claves programaticamente.

Autenticacion

Metodo	Quien	Como
JWT (Bearer token)	Admins del tenant	Token de la sesion del Dashboard. Las claves se asocian a tu tenant automaticamente.
service_role	Admins de la plataforma	Clave interna de servicio. Debe proporcionar header `X-Tenant-Id` o `tenant_id` en el body.

Prevencion BOLA: Al usar autenticacion JWT, el campo tenant_id en el body de la solicitud es ignorado. La API siempre usa el tenant de tu sesion — no puedes crear ni gestionar claves de otros tenants.

Crear una Clave

cURL (JWT)
cURL (service_role)
JavaScript

# Obtiene tu JWT de la sesion del Dashboard
curl -X POST https://api-staging.play2sell.com/functions/v1/api-key-admin \
  -H "Authorization: Bearer TU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "key_name": "Sincronizacion CRM Nocturna",
    "scopes": ["default:sync"],
    "rate_limit_per_hour": 5000,
    "expires_in_days": 90,
    "environment": "live"
  }'

curl -X POST https://api-staging.play2sell.com/functions/v1/api-key-admin \
  -H "Authorization: Bearer SUPABASE_SERVICE_ROLE_KEY" \
  -H "X-Tenant-Id: UUID_DEL_TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "UUID_DEL_TENANT",
    "key_name": "Sincronizacion CRM Nocturna",
    "scopes": ["default:sync"],
    "rate_limit_per_hour": 5000
  }'

const response = await fetch(
  'https://api-staging.play2sell.com/functions/v1/api-key-admin',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      key_name: 'Sincronizacion CRM Nocturna',
      scopes: ['default:sync'],
      rate_limit_per_hour: 5000,
      expires_in_days: 90,
    }),
  }
);

const { api_key, warning } = await response.json();
console.log('Guarda esta clave:', api_key);
// => sk_live_a1b2c3d4e5f6...

Respuesta (201):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "key_prefix": "sk_live_",
  "key_last_4": "f6g7",
  "scopes": ["default:sync"],
  "rate_limit_per_hour": 5000,
  "expires_at": "2026-06-17T00:00:00.000Z",
  "created_at": "2026-03-17T14:30:00.000Z",
  "tenant_id": "b2c3d4e5-f6g7-8901-abcd-ef2345678901",
  "tenant_name": "Acme Corp",
  "api_key": "sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0",
  "warning": "Save this API key now. It cannot be retrieved again."
}

El campo api_key se muestra solo una vez. Si lo pierdes, deberas crear una nueva clave.

Listar Claves

curl https://api-staging.play2sell.com/functions/v1/api-key-admin \
  -H "Authorization: Bearer TU_TOKEN_JWT"

Respuesta (200):

{
  "keys": [
    {
      "id": "a1b2c3d4-...",
      "key_name": "Sincronizacion CRM Nocturna",
      "key_prefix": "sk_live_",
      "key_last_4": "f6g7",
      "scopes": ["default:sync"],
      "status": "active",
      "rate_limit_per_hour": 5000,
      "usage_count": 1247,
      "last_used_at": "2026-03-17T10:00:00.000Z",
      "expires_at": "2026-06-17T00:00:00.000Z",
      "created_at": "2026-03-01T09:00:00.000Z",
      "revoked_at": null,
      "revoked_reason": null
    }
  ],
  "total": 1
}

La clave completa y el hash nunca se retornan en las respuestas de listado.

Revocar una Clave

curl -X PUT https://api-staging.play2sell.com/functions/v1/api-key-admin/KEY_UUID/revoke \
  -H "Authorization: Bearer TU_TOKEN_JWT" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Rotacion de credenciales"}'

Respuesta (200):

{
  "id": "a1b2c3d4-...",
  "key_name": "Sincronizacion CRM Nocturna",
  "key_prefix": "sk_live_",
  "key_last_4": "f6g7",
  "status": "revoked",
  "revoked_at": "2026-03-17T15:00:00.000Z",
  "revoked_reason": "Rotacion de credenciales"
}

Eliminar una Clave

curl -X DELETE https://api-staging.play2sell.com/functions/v1/api-key-admin/KEY_UUID \
  -H "Authorization: Bearer TU_TOKEN_JWT"

Prefiere revocar en vez de eliminar. Las claves revocadas preservan el historial de auditoria (quien la creo, cuando se uso, por que fue revocada).

Alcances Disponibles

Alcance	Concede acceso a
`default:sync`	Endpoints `sync_collaborators` y `sync_activities`
`leads:read`	Lectura de datos de leads
`leads:write`	Creacion y actualizacion de leads

Un array scopes vacio significa que la clave no tiene restriccion de alcance — puede acceder a cualquier endpoint que acepte autenticacion por API key.

Mejores Practicas

Usa claves diferentes para cada integracion

Crea claves separadas para cada integracion (sincronizacion CRM, formularios del sitio, API de socios). Asi, si una clave se compromete, solo necesitas rotar esa.

Establece fechas de expiracion

Las claves sin expiracion viven para siempre. Establece expires_in_days para forzar rotacion regular — 90 dias es un buen valor por defecto.

Usa alcances minimos

Si una clave solo necesita sincronizar actividades, dale solo default:sync. No dejes los alcances vacios a menos que la clave realmente necesite acceso total.

Monitorea el uso

Revisa usage_count y last_used_at en la respuesta de listado. Las claves no usadas en meses pueden ser candidatas a revocacion.

Rota claves sin tiempo de inactividad

Crea una nueva clave
Actualiza tu integracion para usar la nueva clave
Verifica que la nueva clave funciona
Revoca la clave anterior

Proximos Pasos

Autenticacion

Conoce mas sobre los formatos de API key y seguridad

Integracion por Defecto

Comienza a enviar actividades con tu nueva clave

Descripción General

Integraciones

​Gestion de API Keys

Desde el Dashboard

Via API

​Desde el Dashboard

​Gestionando claves en el Dashboard

​Via API

​Autenticacion

​Crear una Clave

​Listar Claves

​Revocar una Clave

​Eliminar una Clave

​Alcances Disponibles

​Mejores Practicas

​Proximos Pasos

Autenticacion

Integracion por Defecto

Gestion de API Keys

Desde el Dashboard

Gestionando claves en el Dashboard

Via API

Autenticacion

Crear una Clave

Listar Claves

Revocar una Clave

Eliminar una Clave

Alcances Disponibles

Mejores Practicas

Proximos Pasos