API pública — Share Auth

Consultar as contas 2FA de uma equipa e obter os seus códigos TOTP a partir das suas ferramentas, com um token próprio.

A API permite a um cliente autorizado consultar as contas 2FA de uma equipa e obter os respetivos códigos TOTP.

export API_URL="https://app.shareauth.net"
export API_TOKEN="1|o-seu-token-sanctum"

Use exclusivamente HTTPS em produção. Os pedidos e as respostas estão em formato JSON.

Autenticação

Crie um token Sanctum:

curl -X POST "$API_URL/api/tokens/create" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email":"[email protected]",
    "password":"palavra-passe",
    "device_name":"o-meu-conector",
    "code":"123456"
  }'

O campo code só é obrigatório se a conta proteger o seu início de sessão com 2FA. recovery_code pode substituí-lo.

Resposta:

{
  "token": "1|abcdefghijklmnopqrstuvwxyz",
  "user": {
    "id": 12,
    "name": "Alice",
    "email": "[email protected]"
  }
}

Guarde este token como um segredo e transmita-o depois no cabeçalho:

Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz
Accept: application/json

Equipa ativa

Os códigos devolvidos pertencem sempre à equipa ativa do utilizador.

Listar as equipas acessíveis:

curl "$API_URL/api/v1/teams" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Mudar de equipa ativa:

curl -X POST "$API_URL/api/v1/teams/42/switch" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Listar as contas 2FA

curl "$API_URL/api/v1/secrets" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Resposta abreviada:

{
  "data": [
    {
      "id": 7,
      "name": "GitHub production",
      "issuer": "GitHub",
      "digits": 6,
      "period": 30
    }
  ],
  "meta": {
    "total": 1,
    "limit": 10,
    "remaining": 9
  }
}

A semente TOTP nunca é incluída nas respostas.

Obter um código

Use o identificador devolvido pela lista:

curl -X POST "$API_URL/api/v1/secrets/7/generate" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Resposta:

{
  "data": {
    "secret_name": "GitHub production",
    "code": "123456",
    "next_code": "654321",
    "time_remaining": 18,
    "period": 30,
    "expires_at": "2026-08-13T12:00:30.000000Z"
  }
}

Cada geração fica registada no registo de acessos da equipa. Não registe o código do lado do cliente.

Erros

Estado	Significado
`401`	token ausente ou inválido
`403`	acesso recusado ou segredo fora da equipa ativa
`404`	recurso não encontrado
`422`	dados inválidos, equipa ausente ou código impossível de gerar
`429`	limite de 60 pedidos por minuto ultrapassado

Um erro de validação segue geralmente este formato:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email field is required."]
  }
}

Conector MCP

O conector pronto a usar para o ChatGPT, o Codex, o Claude e outros clientes MCP está documentado em mcp-server/README.md, no repositório do projeto.