Autenticación

Claves API

AdaptlyPost utiliza claves API para autenticar las solicitudes de la REST API. Puede generar y administrar claves API desde su panel de control en Gestionar > API y agentes de IA.

Uso de su clave API

Incluya su clave API en el encabezado Authorization de cada solicitud:

Authorization: Bearer your_api_key_here

Solicitud de ejemplo

curl https://post.adaptlypost.com/post/api/v1/social-accounts \
  -H "Authorization: Bearer adaptly_8f3c1d9a7b2e4605c1a8d7f36b904e2d"

Roles y permisos

Cada miembro de un espacio de trabajo tiene uno de cuatro roles. El rol decide qué puede hacer el miembro en el panel y qué puede hacer cualquier clave de API, sesión MCP o integración que actúe en su nombre. La comprobación se ejecuta en el servidor en cada solicitud, así que un cliente no puede saltársela.

Permisos por rol

Cada página de endpoint indica el permiso que necesita. Una clave tiene exactamente los permisos de su rol, menos lo que su creador ya no puede hacer. GET /api/v1/me devuelve la lista.

Las claves llevan un rol

Al crear una clave eliges su rol. La clave actúa entonces con ese rol en el espacio de trabajo donde se creó, según estas reglas:

• Una clave nunca puede crearse con un rol superior al del miembro que la crea. Un Editor puede emitir claves de Editor, Colaborador o Visor, no de Administrador.
• En cada solicitud, los permisos efectivos de la clave son los de su rol, menos lo que su creador ya no puede hacer. La comprobación lee el rol actual del creador, no el rol en el momento de la creación.
• Si el creador es degradado, todas las claves que creó se reducen con él al instante. Una clave de Editor creada por un miembro que ahora es Colaborador solo puede crear borradores.
• Si el creador abandona el espacio de trabajo o es eliminado, sus claves dejan de funcionar y responden 401 con code token_issuer_lost_access. Un administrador del espacio de trabajo crea una de repuesto.
• Una sesión MCP o una concesión OAuth no tiene rol propio: actúa con el rol del miembro que inició sesión en el espacio de trabajo al que llega la llamada. Es su espacio de trabajo predeterminado, salvo que X-Workspace-Id nombre otro.

Elegir un espacio de trabajo

Un miembro puede pertenecer a varios espacios de trabajo, en una o varias organizaciones. Una conexión OAuth, como el conector de Claude o ChatGPT, puede actuar en cualquiera de ellos. Una clave de API solo actúa en el espacio de trabajo en el que se creó. Envía la cabecera opcional X-Workspace-Id en cualquier petición para elegir el espacio de trabajo. Sin ella, la llamada llega al espacio de trabajo predeterminado.

X-Workspace-Id: ag_02k7m

Este endpoint lista los id de espacio de trabajo que puedes enviar, con tu rol y un objeto can para cada uno: GET /api/v1/workspaces

Errores de autenticación

Una clave ausente, inválida o caducada responde 401. Una clave que existe pero no puede hacer lo que pediste responde 403. Cada cuerpo de error lleva un code legible por máquina para que un cliente los distinga:

{
  "statusCode": 401,
  "message": "Invalid or missing API key",
  "error": "Unauthorized"
}

La clave es válida pero el miembro que la creó ya no pertenece al espacio de trabajo. La clave queda inutilizada para siempre; pide una nueva a un administrador del espacio de trabajo.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "code": "token_issuer_lost_access",
  "message": "This API key no longer works: the member who created it lost access to the workspace. Ask a workspace admin for a new key."
}

Un inicio de sesión OAuth, como el conector de Claude o ChatGPT, usó un correo sin cuenta de AdaptlyPost. Desconecta la app y vuelve a conectarla con el correo que usas en AdaptlyPost.

{
  "statusCode": 401,
  "error": "Unauthorized",
  "code": "oauth_account_not_found",
  "message": "You signed in as jane@example.com, which has no AdaptlyPost account. Disconnect this app and connect again with the email you use on AdaptlyPost."
}

El rol de la clave no tiene el permiso que necesita esta operación. El cuerpo indica el permiso que falta, el rol con el que actúa la clave y qué hacer en su lugar. En una operación sobre publicaciones, el permiso necesario depende de la solicitud: publicar ahora necesita posts.publish, un scheduledAt futuro necesita posts.schedule, y tocar la publicación de otro miembro necesita además posts.others.

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "permission_denied",
  "requiredPermission": "posts.publish",
  "role": "contributor",
  "keyRole": "contributor",
  "issuerRole": "editor",
  "tokenType": "api_token",
  "message": "The Contributor role cannot publish posts. Send the post with saveAsDraft: true and ask a workspace member to publish it."
}

El plan de la organización no está activo o no incluye acceso a la API. Cada llamada con la clave o con el inicio de sesión OAuth recibe esta respuesta hasta que se renueve o mejore el plan. code distingue este 403 de los demás.

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "subscription_required",
  "message": "This API key no longer works: your organization's plan does not include API access. Renew or upgrade the plan to use it again."
}

X-Workspace-Id nombra un espacio de trabajo al que quien llama no tiene acceso. Una clave de API recibe la misma respuesta para cualquier espacio de trabajo que no sea el suyo. Envía un id de GET /api/v1/workspaces o quita la cabecera.

{
  "statusCode": 403,
  "error": "Forbidden",
  "code": "workspace_access_denied",
  "workspaceId": "ag_03p4r",
  "message": "You have no access to workspace ag_03p4r. Call GET /workspaces to list the workspaces you can use, and send one of those ids in the X-Workspace-Id header."
}

Para equipos regulados

Un asiento de Colaborador y una clave de Colaborador se aplican en el servidor, no en la interfaz. Cada solicitud, ya venga del panel, de la API REST, del servidor MCP o de una integración como Zapier o n8n, pasa por la misma comprobación de permisos en el servicio de publicaciones antes de escribir nada: la comprobación lee el rol del solicitante en el espacio de trabajo en ese momento, deduce el permiso que necesita la solicitud a partir de sus hechos (borrador, programada o publicar ahora; publicación propia o de un compañero) y rechaza con un 403 cuando falta. Una clave se crea bajo un rol, nunca por encima del miembro que la crea, y sus permisos se recalculan en cada llamada como la intersección entre el rol de la clave y el rol actual de su creador, así que degradar al creador reduce la clave al instante y eliminarlo la anula. Un auditor puede señalar tres cosas: GET /api/v1/me, que devuelve el rol y la lista exacta de permisos que tiene una clave ahora mismo; el cuerpo del 403, que nombra el permiso que faltaba, el rol que no lo tenía y el tipo de token que lo intentó; y el registro de auditoría de publicaciones, donde cada intento de crear, programar, publicar, reintentar o eliminar queda registrado con quién lo hizo, con qué clave, bajo qué rol, de qué estado a cuál, y si se permitió o se rechazó. El registro lo escribe el servicio de publicaciones; todavía no se puede consultar desde el panel ni desde la API.