Documentation

API publique

Consultez les comptes 2FA d’une équipe et récupérez leurs codes TOTP depuis vos propres outils, avec un jeton dédié.

L’API permet à un client autorisé de consulter les comptes 2FA d’une équipe et de récupérer leurs codes TOTP.

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

Utilisez uniquement HTTPS en production. Les requêtes et réponses sont au format JSON.

Authentification

Chaque appel porte un token Sanctum dans l’en-tête :

Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz
Accept: application/json

Créer un token depuis l’application

C’est la voie recommandée. Dans votre profil, section Jetons API, choisissez les permissions et la durée de validité ; le mot de passe est redemandé, et le token n’est affiché qu’une fois.

Créer un token par l’API

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

Le second facteur est obligatoire, sous l’une de ces formes :

  • compte protégé par une application d’authentification : le code à six chiffres dans code, ou un code de secours dans recovery_code ;

  • compte sans application d’authentification : le premier appel, sans code, ne crée rien. Il répond 409 et envoie un code à six chiffres par e-mail :

    {
      "message": "Nous vous avons envoyé un code à six chiffres par e-mail. Renvoyez cette requête avec ce code dans confirmation_code.",
      "confirmation_required": true
    }
    

    Renvoyez la même requête avec ce code dans confirmation_code. Il ne sert qu’une fois et expire au bout de 15 minutes.

Réponse :

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

Conservez ce token comme un secret.

Permissions et durée

PermissionDonne accès à
secrets:listla liste des comptes 2FA et le détail d’un compte
secrets:generatele code courant d’un compte
teams:readles équipes, leurs membres et le changement d’équipe active
audit:readle journal d’accès (propriétaire de l’équipe)
integrations:manageles intégrations de messagerie (propriétaire de l’équipe)

Sans abilities, le token reçoit les cinq permissions : demandez seulement celles dont votre outil a besoin. expires_in_days vaut 1, 7, 30 ou 90, et 30 par défaut. Un compte compte au plus dix tokens actifs ; les tokens expirés sont retirés automatiquement, les autres se révoquent depuis le profil.

Créer, modifier ou supprimer des secrets et des équipes se fait dans l’application : aucun token ne peut recevoir ces droits.

Équipe active

Les codes retournés appartiennent toujours à l’équipe active de l’utilisateur.

Lister les équipes accessibles :

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

Changer d’équipe active (permission teams:read) :

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

Lister les comptes 2FA

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

Réponse abrégée :

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

La graine TOTP n’est jamais incluse dans les réponses.

Récupérer un code

Utilisez l’identifiant retourné par la liste :

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

Réponse :

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

Chaque génération est enregistrée dans le journal d’accès de l’équipe. Ne journalisez pas le code côté client.

Journal d’accès

Réservé au propriétaire de l’équipe active, avec un token portant la permission audit:read. Le journal couvre le site, l’API et les bots de messagerie.

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

Filtres facultatifs :

ParamètreValeurs
secret_ididentifiant d’un secret de l’équipe
actionlist, view ou generate
channelweb, api, slack, discord ou teams
limitde 1 à 500, 100 par défaut

Réponse :

{
  "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 vaut false pour un bot : le nom et external_id sont ceux que la plateforme a déclarés, sans compte Share Auth derrière. actor.deleted signale un compte supprimé depuis.
  • meta.visible_since est le début de la période lisible avec le forfait (7 jours en Gratuit, 90 en Équipe), null en Business. meta.hidden compte les entrées plus anciennes, conservées mais masquées.

Erreurs

StatutSignification
401token absent ou invalide
403accès refusé ou secret hors de l’équipe active
404ressource introuvable
422données invalides, équipe absente ou code impossible à générer
429limite de 60 requêtes par minute dépassée

Une erreur de validation suit généralement ce format :

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

Connecteur MCP

Le connecteur MCP donne aux assistants IA (ChatGPT, Codex, Claude et les autres clients MCP) deux outils : lister les comptes 2FA de l’équipe et obtenir le code courant. Il ne lit ni ne renvoie jamais la graine TOTP, et chaque code obtenu figure dans le journal d’accès. Il s’authentifie avec un jeton limité à secrets:list et secrets:generate.

Le connecteur est présenté en détail sur la page Agents IA (MCP). Son code est public sur GitHub, comme celui de la skill 2FA pour agents.