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 inrecovery_code;account senza app di autenticazione: la prima chiamata, senza
code, non crea nulla. Risponde409e 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
| Permesso | Dà accesso a |
|---|---|
secrets:list | l’elenco degli account 2FA e il dettaglio di un account |
secrets:generate | il codice corrente di un account |
teams:read | i team, i loro membri e il cambio di team attivo |
audit:read | il registro degli accessi (proprietario del team) |
integrations:manage | le 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:
| Parametro | Valori |
|---|---|
secret_id | identificativo di un segreto del team |
action | list, view o generate |
channel | web, api, slack, discord o teams |
limit | da 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.verifiedvalefalseper un bot: il nome eexternal_idsono quelli dichiarati dalla piattaforma, senza un account Share Auth dietro.actor.deletedsegnala un account eliminato nel frattempo.meta.visible_sinceè l’inizio del periodo consultabile con il piano (7 giorni con Gratuito, 90 con Team),nullcon Business.meta.hiddenconta le voci più vecchie, conservate ma nascoste.
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 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.