Documentazione

API pubblica

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

Ogni chiamata include un token Sanctum nell’intestazione:

Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz
Accept: application/json

Creare un token dall’applicazione

È la via consigliata. Nel tuo profilo, sezione Token API, scegli i permessi e la durata di validità; la password viene richiesta di nuovo e il token viene mostrato una sola volta.

Creare un token tramite l’API

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

Il secondo fattore è obbligatorio, in una di queste forme:

  • account protetto da un’app di autenticazione: il codice a sei cifre in code, oppure un codice di recupero in recovery_code;

  • account senza app di autenticazione: la prima chiamata, senza code, non crea nulla. Risponde 409 e invia un codice di sei cifre via e-mail:

    {
      "message": "Ti abbiamo inviato un codice di sei cifre via e-mail. Ripeti questa richiesta con quel codice in confirmation_code.",
      "confirmation_required": true
    }
    

    Ripeti la stessa richiesta con quel codice in confirmation_code. Vale una sola volta e scade dopo 15 minuti.

Risposta:

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

Conserva questo token come un segreto.

Permessi e durata

PermessoDà accesso a
secrets:listl’elenco degli account 2FA e il dettaglio di un account
secrets:generateil codice corrente di un account
teams:readi team, i loro membri e il cambio di team attivo
audit:readil registro degli accessi (proprietario del team)
integrations:managele integrazioni di messaggistica (proprietario del team)

Senza abilities, il token riceve tutti e cinque i permessi: chiedi solo quelli di cui il tuo strumento ha bisogno. expires_in_days vale 1, 7, 30 o 90, e 30 per impostazione predefinita. Un account ha al massimo dieci token attivi; i token scaduti vengono rimossi automaticamente, gli altri si revocano dal profilo.

Creare, modificare o eliminare segreti e team si fa nell’applicazione: nessun token può ricevere questi diritti.

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 (permesso teams:read):

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.

Registro degli accessi

Riservato al proprietario del team attivo, con un token che abbia il permesso audit:read. Il registro copre il sito, l’API e i bot di messaggistica.

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

Filtri facoltativi:

ParametroValori
secret_ididentificativo di un segreto del team
actionlist, view o generate
channelweb, api, slack, discord o teams
limitda 1 a 500, 100 per impostazione predefinita

Risposta:

{
  "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 per un bot: il nome e external_id sono quelli dichiarati dalla piattaforma, senza un account Share Auth dietro. actor.deleted segnala un account eliminato nel frattempo.
  • meta.visible_since è l’inizio del periodo consultabile con il piano (7 giorni con Gratuito, 90 con Team), null con Business. meta.hidden conta le voci più vecchie, conservate ma nascoste.

Errori

StatoSignificato
401token assente o non valido
403accesso negato o segreto fuori dal team attivo
404risorsa non trovata
422dati non validi, team assente o codice impossibile da generare
429limite 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 MCP offre agli assistenti IA (ChatGPT, Codex, Claude e altri client MCP) due strumenti: elencare gli account 2FA del team e ottenere il codice corrente. Non legge né restituisce mai il seme TOTP, e ogni codice ottenuto compare nel registro accessi. Si autentica con un token limitato a secrets:list e secrets:generate.

Il connettore è descritto in dettaglio nella pagina Agenti IA (MCP). Il suo codice è pubblico su GitHub, come quello della skill 2FA per agenti.