Documentatie

Openbare API

De 2FA-accounts van een team opvragen en hun TOTP-codes ophalen vanuit je eigen tools, met een eigen token.

Met de API kan een bevoegde client de 2FA-accounts van een team opvragen en hun TOTP-codes ophalen.

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

Gebruik in productie uitsluitend HTTPS. Verzoeken en antwoorden zijn in JSON-formaat.

Authenticatie

Elke aanroep stuurt een Sanctum-token mee in de header:

Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz
Accept: application/json

Een token aanmaken in de applicatie

Dit is de aanbevolen weg. Kies in je profiel, onder API-tokens, de permissies en de geldigheidsduur; je wachtwoord wordt opnieuw gevraagd, en het token wordt maar één keer getoond.

Een token aanmaken via de API

curl -X POST "$API_URL/api/tokens/create" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "wachtwoord",
    "device_name": "mijn-connector",
    "abilities": ["secrets:list", "secrets:generate"],
    "expires_in_days": 30,
    "code": "123456"
  }'

De tweede factor is verplicht, in een van deze vormen:

  • account beschermd met een authenticatie-app: de zescijferige code in code, of een herstelcode in recovery_code;

  • account zonder authenticatie-app: de eerste aanroep, zonder code, maakt niets aan. Hij antwoordt met 409 en stuurt een zescijferige code per e-mail:

    {
      "message": "We hebben u een zescijferige code gemaild. Verstuur dit verzoek opnieuw met die code als confirmation_code.",
      "confirmation_required": true
    }
    

    Stuur hetzelfde verzoek opnieuw met die code in confirmation_code. Hij is maar één keer bruikbaar en verloopt na 15 minuten.

Antwoord:

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

Bewaar dit token als een geheim.

Permissies en duur

PermissieGeeft toegang tot
secrets:listde lijst van 2FA-accounts en de details van een account
secrets:generatede actuele code van een account
teams:readde teams, hun leden en het wisselen van actief team
audit:readhet toegangslogboek (eigenaar van het team)
integrations:managede integraties met chatplatforms (eigenaar van het team)

Zonder abilities krijgt het token alle vijf permissies: vraag alleen de permissies aan die je tool nodig heeft. expires_in_days is 1, 7, 30 of 90, en standaard 30. Een account heeft hoogstens tien actieve tokens; verlopen tokens worden automatisch verwijderd, de andere trek je in vanuit je profiel.

Geheimen en teams aanmaken, wijzigen of verwijderen doe je in de applicatie: geen enkel token kan die rechten krijgen.

Actief team

De teruggegeven codes horen altijd bij het actieve team van de gebruiker.

De bereikbare teams opvragen:

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

Van actief team wisselen (permissie teams:read):

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

De 2FA-accounts opvragen

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

Ingekort antwoord:

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

De TOTP-seed zit nooit in de antwoorden.

Een code ophalen

Gebruik de identificatie die de lijst teruggeeft:

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

Antwoord:

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

Elke generatie wordt vastgelegd in het toegangslogboek van het team. Log de code niet aan de clientzijde.

Toegangslogboek

Alleen de eigenaar van het actieve team kan het logboek lezen, met een token dat de permissie audit:read heeft. Het omvat de website, de API en de bots van berichtendiensten.

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

Optionele filters:

ParameterWaarden
secret_idid van een geheim van het team
actionlist, view of generate
channelweb, api, slack, discord of teams
limitvan 1 tot 500, standaard 100

Antwoord:

{
  "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 is false voor een bot: de naam en external_id komen van het platform, zonder Share Auth-account erachter. actor.deleted geeft aan dat het account sindsdien is verwijderd.
  • meta.visible_since is het begin van de periode die met het abonnement leesbaar is (7 dagen bij Gratis, 90 bij Team), null bij Business. meta.hidden telt de oudere vermeldingen, die bewaard maar verborgen zijn.

Fouten

StatusBetekenis
401token ontbreekt of is ongeldig
403toegang geweigerd of geheim buiten het actieve team
404bron niet gevonden
422ongeldige gegevens, ontbrekend team of code niet te genereren
429limiet van 60 verzoeken per minuut overschreden

Een validatiefout heeft doorgaans deze vorm:

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

MCP-connector

De MCP-connector geeft AI-assistenten (ChatGPT, Codex, Claude en andere MCP-clients) twee tools: de 2FA-accounts van het team opsommen en de huidige code ophalen. Hij leest of retourneert nooit het TOTP-geheim, en elke opgehaalde code verschijnt in het toegangslogboek. Hij authenticeert met een token dat beperkt is tot secrets:list en secrets:generate.

De connector wordt uitgebreid beschreven op de pagina AI-agents (MCP). Zijn code is openbaar op GitHub, net als die van de 2FA-skill voor agents.