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 emrecovery_code;conta sem aplicação de autenticação: a primeira chamada, sem
code, não cria nada. Responde409e 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ão | Dá acesso a |
|---|---|
secrets:list | a lista das contas 2FA e o detalhe de uma conta |
secrets:generate | o código atual de uma conta |
teams:read | as equipas, os seus membros e a mudança de equipa ativa |
audit:read | o registo de acessos (proprietário da equipa) |
integrations:manage | as 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âmetro | Valores |
|---|---|
secret_id | identificador de um segredo da equipa |
action | list, view ou generate |
channel | web, api, slack, discord ou teams |
limit | de 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.verifiedvalefalsepara um bot: o nome e oexternal_idvêm da plataforma, sem conta Share Auth por trás.actor.deletedassinala 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),nullno Business.meta.hiddenconta as entradas mais antigas, conservadas mas ocultas.
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 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.