Documentação

API pública

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

Cada chamada leva um token Sanctum no cabeçalho:

Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz
Accept: application/json

Criar um token a partir da aplicação

É a via recomendada. No seu perfil, na secção Tokens de API, escolha as permissões e o prazo de validade; a palavra-passe é pedida de novo, e o token só é mostrado uma vez.

Criar um token pela API

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",
    "abilities": ["secrets:list", "secrets:generate"],
    "expires_in_days": 30,
    "code": "123456"
  }'

O segundo fator é obrigatório, sob uma destas formas:

  • conta protegida por uma aplicação de autenticação: o código de seis dígitos em code, ou um código de recuperação em recovery_code;

  • conta sem aplicação de autenticação: a primeira chamada, sem code, não cria nada. Responde 409 e envia um código de seis dígitos por e-mail:

    {
      "message": "Enviámos-lhe um código de seis dígitos por e-mail. Repita este pedido com esse código em confirmation_code.",
      "confirmation_required": true
    }
    

    Repita o mesmo pedido com esse código em confirmation_code. Só pode ser usado uma vez e expira ao fim de 15 minutos.

Resposta:

{
  "token": "1|abcdefghijklmnopqrstuvwxyz",
  "abilities": ["secrets:list", "secrets:generate"],
  "expires_at": "2026-11-18T10:00:00.000000Z",
  "user": {
    "id": 12,
    "name": "Alice",
    "email": "[email protected]"
  }
}

Guarde este token como um segredo.

Permissões e duração

PermissãoDá acesso a
secrets:lista lista das contas 2FA e o detalhe de uma conta
secrets:generateo código atual de uma conta
teams:readas equipas, os seus membros e a mudança de equipa ativa
audit:reado registo de acessos (proprietário da equipa)
integrations:manageas integrações de mensagens (proprietário da equipa)

Sem abilities, o token recebe as cinco permissões: peça apenas aquelas de que a sua ferramenta precisa. expires_in_days vale 1, 7, 30 ou 90, e 30 por omissão. Cada conta tem no máximo dez tokens ativos; os tokens expirados são removidos automaticamente, os outros revogam-se a partir do perfil.

Criar, alterar ou eliminar segredos e equipas faz-se na aplicação: nenhum token pode receber esses direitos.

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 (permissão teams:read):

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.

Registo de acessos

Só o proprietário da equipa ativa o pode consultar, com um token que tenha a permissão audit:read. O registo abrange o sítio, a API e os bots de mensagens.

curl "$API_URL/api/v1/access-logs?channel=slack&limit=50" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Accept: application/json"

Filtros opcionais:

ParâmetroValores
secret_ididentificador de um segredo da equipa
actionlist, view ou generate
channelweb, api, slack, discord ou teams
limitde 1 a 500, 100 por predefinição

Resposta:

{
  "data": [
    {
      "id": 412,
      "actor": {
        "id": null,
        "name": "sam",
        "email": null,
        "external_id": "U04ABCDEF",
        "verified": false,
        "deleted": false
      },
      "bot_integration_id": 3,
      "secret": { "id": 7, "name": "GitHub production", "deleted": false },
      "action": "generate",
      "channel": "slack",
      "ip_address": null,
      "occurred_at": "2026-10-19T09:41:00.000000Z"
    }
  ],
  "meta": {
    "total": 1,
    "disclosures": 1,
    "visible_since": "2026-07-21T00:00:00.000000Z",
    "hidden": 0
  }
}
  • actor.verified vale false para um bot: o nome e o external_id vêm da plataforma, sem conta Share Auth por trás. actor.deleted assinala uma conta entretanto eliminada.
  • meta.visible_since é o início do período legível com o plano (7 dias no Gratuito, 90 no Equipa), null no Business. meta.hidden conta as entradas mais antigas, conservadas mas ocultas.

Erros

EstadoSignificado
401token ausente ou inválido
403acesso recusado ou segredo fora da equipa ativa
404recurso não encontrado
422dados inválidos, equipa ausente ou código impossível de gerar
429limite 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 MCP dá aos assistentes de IA (ChatGPT, Codex, Claude e outros clientes MCP) duas ferramentas: listar as contas 2FA da equipa e obter o código atual. Nunca lê nem devolve a semente TOTP, e cada código obtido aparece no registo de acessos. Autentica-se com um token limitado a secrets:list e secrets:generate.

O conector é descrito em detalhe na página Agentes de IA (MCP). O seu código é público no GitHub, tal como o da skill 2FA para agentes.