Tokens de API y despliegue desde CI

Las cookies de sesión son para los navegadores. Para scripts, herramientas de CLI y ejecutores de CI — cualquier cosa que no pueda transportar una cookie — Pier emite tokens de API Bearer. Un token se autentica como el usuario que lo creó y hereda los roles de ese usuario, de modo que un token de CI solo puede desplegar los servicios que su propietario podría desplegar.

Los tokens se almacenan como un hash SHA-256; el texto plano se muestra una sola vez en el momento de la creación y nunca es recuperable.

Crear un token

Desde el área de Cuenta (o directamente contra la API, con una sesión):

Crear — POST /api/v1/account/tokens con un name. La respuesta incluye el token en texto plano exactamente una vez. Cópialo ahora.
Listar — GET /api/v1/account/tokens. Devuelve el id, name, prefix y last_used_at de cada token — nunca el secreto.
Revocar — DELETE /api/v1/account/tokens/{id}. Idempotente; la revocación surte efecto de inmediato en la siguiente solicitud.

Cada token emitido lleva el prefijo pier_npm_, de modo que un token filtrado se reconoce de un vistazo. Envíalo en una cabecera Authorization: Bearer:

Authorization: Bearer pier_npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Trata el token como una contraseña. Cualquiera que lo posea actúa como tú, limitado a tus roles. Guárdalo en el almacén de secretos de tu proveedor de CI, nunca en el repositorio.

Disparar un despliegue desde CI

Dos endpoints de despliegue autenticados aceptan un token Bearer. Ambos ejecutan la misma canalización y devuelven un deployment_id que puedes consultar.

Endpoint	Úsalo cuando CI conozca…
`POST /api/v1/services/{id}/deploy`	el id del servicio
`POST /api/v1/projects/{id}/services/{name}/deploy`	el id del proyecto y el nombre del servicio

La autorización requiere el rol Editor de proyecto sobre el servicio de destino (el rol de proyecto del propietario del token). El servicio ya debe tener configurado su repositorio git. Ambos endpoints tienen límite de tasa por IP de cliente, ya que un despliegue es un clonado y compilación costoso.

El cuerpo JSON es opcional. Campos útiles: commit_sha (registrado para trazabilidad), branch (o ref como alias) y message. Si omites la rama, Pier usa la rama configurada del servicio, recurriendo a main.

curl -X POST https://pier.example.com/api/v1/projects/proj_abc123/services/web/deploy \
  -H "Authorization: Bearer pier_npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
        "commit_sha": "'"$GIT_COMMIT"'",
        "branch": "main",
        "message": "CI deploy from pipeline #42"
      }'

Una respuesta exitosa devuelve el id del despliegue y una URL de estado:

{
  "ok": true,
  "deployment_id": "d1e2f3...",
  "service_id": "svc_...",
  "status_url": "/api/v1/resources/svc_.../deployments/d1e2f3..."
}

Consulta GET /api/v1/resources/{id}/deployments/{deployment_id} hasta que la compilación alcance un estado terminal para que tu canalización espere el resultado.

Tokens de API y despliegue desde CI

Crear un token

Disparar un despliegue desde CI

Próximos pasos