Autenticação

Autenticação por Chave de API

Todos os pedidos à API devem incluir a tua chave de API no cabeçalhoAuthorization, utilizando o esquema Bearer token:

Authorization: Bearer flp_your_api_key_here

Criar Chaves de API

Navega até Account → API Keys no teu painel FloopFloop para criar e gerir chaves de API.

• Cada conta pode ter até 5 chaves de API ativas
• As chaves são apresentadas apenas uma vez na criação — guarda-as em segurança
• As chaves podem ser revogadas a qualquer momento no painel
• Todas as chaves começam com o prefixo flp_

Segurança das Chaves

• Nunca partilhes as tuas chaves de API nem as incluas no controlo de versões
• Utiliza variáveis de ambiente para guardar as chaves nas tuas aplicações
• Roda as chaves regularmente e revoga as que não estão a ser utilizadas
• Cada chave tem o seu próprio limite de taxa individual

Limites de Taxa

Os endpoints da API têm os seguintes limites de taxa por chave de API:

As informações sobre limites de taxa estão incluídas nos cabeçalhos de resposta: X-RateLimit-Remaining e X-RateLimit-Reset.

Verificar Autenticação

GET /api/v1/user/me

Utiliza este endpoint para confirmar que a tua chave de API é válida. Devolve o perfil do utilizador autenticado e é a chamada padrão “testa a tua autenticação” utilizada por todos os SDKs oficiais e pelo floop whoami na CLI.

curl https://floopfloop.com/api/v1/user/me \
  -H "Authorization: Bearer flp_your_api_key_here"

Resposta (200):

{
  "data": {
    "id": "user_abc123",
    "email": "you@example.com",
    "name": "Your Name",
    "role": "user",
    "source": "api_key"
  }
}

• role — "user" para contas normais, "admin" para staff da plataforma.
• source — como o pedido foi autenticado. "api_key" para credenciais programáticas, "cli_token" para o fluxo de CLI autorizado por dispositivo.

Um 401 UNAUTHORIZED aqui significa que a chave está em falta, revogada ou malformada. Um 403 FORBIDDENsignifica que a conta existe mas não tem o plano Business que condiciona o acesso à API (consulta Requisitos na Visão Geral da API).

Gestão Programática de Chaves de API

A maioria dos utilizadores cria chaves no painel, mas a mesma funcionalidade está disponível através da API para cenários de orquestração — rodar uma chave a partir de um job CI, listar chaves para auditar o uso, ou revogar uma chave comprometida sem passar pela interface. Isto espelha o quefloop keys list/create/remove faz na CLI.

Listar Chaves de API

GET /api/v1/api-keys

Devolve metadados de todas as chaves ativas (não revogadas) na conta. O material da chave em texto simples nunca é devolvido — apenas o keyPrefix (os primeiros 8 caracteres hexadecimais da chave, com o prefixo flp_).

{
  "data": {
    "keys": [
      {
        "id": "key_abc",
        "name": "ci-deploy",
        "keyPrefix": "flp_a1b2c3d4",
        "scopes": null,
        "lastUsedAt": "2026-04-24T18:30:00Z",
        "createdAt": "2026-04-01T12:00:00Z"
      }
    ]
  }
}

Criar Chave de API

POST /api/v1/api-keys

{
  "name": "ci-deploy"    // required, 1-100 chars
}

Resposta (201):

{
  "data": {
    "id": "key_xyz",
    "rawKey": "flp_a1b2c3d4…full-40-hex…",
    "keyPrefix": "flp_a1b2c3d4"
  }
}

A rawKey é apresentada apenas uma vez— leituras subsequentes devolvem apenas o keyPrefix. Guarda-a imediatamente. Cada conta está limitada a 5 chaves ativas; se atingires o limite, o pedido devolve409 LIMIT_EXCEEDED— revoga primeiro uma chave não utilizada.

Para criar uma chave é necessário o plano Business. Um pedido de uma conta sem Business devolve 403 FORBIDDEN com a mensagem “Creating API keys requires the Business plan”. Os admins da plataforma ignoram esta restrição.

Revogar Chave de API

DELETE /api/v1/api-keys/{keyId}

Passa o id da chave (por exemplo,key_xyz) como parâmetro de caminho. A chave é invalidada imediatamente — os pedidos já em processamento num worker podem ser concluídos, mas nenhum novo pedido será autenticado.

Resposta (200):

{ "data": { "success": true } }

• A auto-revogação está bloqueada. Chamar DELETE com a mesma chave que está a fazer o pedido devolve400 VALIDATION_ERROR— isto impede a CLI de se cortar a meio de uma chamada. Utiliza uma chave diferente, ou revoga no painel.
• Chaves desconhecidas ou já revogadas devolvem404 NOT_FOUND.

Os SDKs oficiais aceitam um id ou o nome da chave nos seus auxiliares apiKeys.remove(), resolvendo nome → id no lado do cliente através de uma chamada de listagem. A API em si aceita apenas o id.

Uma chave revogada não pode ser restaurada; cria uma nova para a substituir. A revogação é registada no registo de auditoria mostrado em Account → API Keys.