API pubblica — Share Auth

Consulta gli account 2FA di un team e recupera i loro codici TOTP dai tuoi strumenti, con un token dedicato.

L’API permette a un client autorizzato di consultare gli account 2FA di un team e di recuperarne i codici TOTP.

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

In produzione usa esclusivamente HTTPS. Richieste e risposte sono in formato JSON.

Autenticazione

Crea un token Sanctum:

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

Il campo code è richiesto solo se l’account protegge il proprio accesso con la 2FA. recovery_code può sostituirlo.

Risposta:

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

Conserva questo token come un segreto e trasmettilo poi nell’intestazione:

Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz
Accept: application/json

Team attivo

I codici restituiti appartengono sempre al team attivo dell’utente.

Elencare i team accessibili:

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

Cambiare team attivo:

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

Elencare gli account 2FA

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

Risposta abbreviata:

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

Il seed TOTP non è mai incluso nelle risposte.

Recuperare un codice

Usa l’identificativo restituito dall’elenco:

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

Risposta:

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

Ogni generazione viene registrata nel registro degli accessi del team. Non registrare il codice lato client.

Errori

Stato	Significato
`401`	token assente o non valido
`403`	accesso negato o segreto fuori dal team attivo
`404`	risorsa non trovata
`422`	dati non validi, team assente o codice impossibile da generare
`429`	limite di 60 richieste al minuto superato

Un errore di validazione segue generalmente questo formato:

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

Connettore MCP

Il connettore pronto all’uso per ChatGPT, Codex, Claude e altri client MCP è documentato in mcp-server/README.md, nel repository del progetto.