Autenticación

Cada punto final API protegido espera un token de acceso OAuth, enviado como token de portador en el encabezado Authorization. Esta página cubre cómo enviarlo y las convenciones que se aplican a cada solicitud.

Obtener una ficha

Obtiene un token de acceso a través del flujo OAuth de Epismo (consulte OAuth para ver la secuencia completa). Si está integrando el cliente CLI o MCP, utilice los puntos finales de token] específicos del producto, que devuelven un token de acceso listo para usar (y un token de actualización) directamente.

Los tokens de acceso son de corta duración. Cuando uno caduque, intercambie el token de actualización por un nuevo token de acceso en lugar de enviar al usuario a iniciar sesión nuevamente. Las solicitudes con un token faltante o vencido devuelven 401.

Enviando el token

curl https://api.epismo.ai/v1/packs/search \
  -H "authorization: Bearer $EPISMO_TOKEN" \
  -H "content-type: application/json" \
  -d '{"type":"context","query":"onboarding"}'

Alcances

Los tokens tienen alcances que determinan lo que pueden hacer:

• Los puntos finales de lectura requieren un alcance de lectura.
• Los puntos finales de mutación (creación, actualización, eliminación) requieren un alcance de escritura.

Si un token carece del alcance que necesita un punto final, la solicitud devuelve 403. Solicite solo los alcances que realmente utiliza su integración.

Contexto del espacio de trabajo

Muchos puntos finales /v1 pueden actuar dentro de un espacio de trabajo específico. Pase el espacio de trabajo como parámetro de consulta workspaceId:

curl "https://api.epismo.ai/v1/projects?workspaceId=$WORKSPACE_ID" \
  -H "authorization: Bearer $EPISMO_TOKEN"

Si omite workspaceId, la solicitud se ejecuta en el contexto predeterminado del token o en el espacio personal cuando el token no tiene ninguno. Para un comportamiento predecible, especialmente en sistemas automatizados, pase workspaceId explícitamente.

Solicitar convenciones

Estos se mantienen en todo el API, por lo que los ejemplos se mantienen consistentes:

• Enviar carrocerías JSON con content-type: application/json.
• Las fechas utilizan YYYY-MM-DD.
• Las llamadas de creación y actualización toman un único scope; las llamadas de búsqueda toman scopes.
• Las actualizaciones utilizan la semántica PATCH a menos que una página indique lo contrario: los campos omitidos no se modifican.

Cuando una solicitud falla, la respuesta lleva un campo error. Consulte Errors para obtener la lista completa de códigos de estado y cómo manejarlos.