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 inrecovery_code;account zonder authenticatie-app: de eerste aanroep, zonder
code, maakt niets aan. Hij antwoordt met409en 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
| Permissie | Geeft toegang tot |
|---|---|
secrets:list | de lijst van 2FA-accounts en de details van een account |
secrets:generate | de actuele code van een account |
teams:read | de teams, hun leden en het wisselen van actief team |
audit:read | het toegangslogboek (eigenaar van het team) |
integrations:manage | de 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:
| Parameter | Waarden |
|---|---|
secret_id | id van een geheim van het team |
action | list, view of generate |
channel | web, api, slack, discord of teams |
limit | van 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.verifiedisfalsevoor een bot: de naam enexternal_idkomen van het platform, zonder Share Auth-account erachter.actor.deletedgeeft aan dat het account sindsdien is verwijderd.meta.visible_sinceis het begin van de periode die met het abonnement leesbaar is (7 dagen bij Gratis, 90 bij Team),nullbij Business.meta.hiddentelt de oudere vermeldingen, die bewaard maar verborgen zijn.
Fouten
| Status | Betekenis |
|---|---|
401 | token ontbreekt of is ongeldig |
403 | toegang geweigerd of geheim buiten het actieve team |
404 | bron niet gevonden |
422 | ongeldige gegevens, ontbrekend team of code niet te genereren |
429 | limiet 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.