Documentación

API pública

Consulta las cuentas 2FA de un equipo y obtén sus códigos TOTP desde tus propias herramientas, con un token propio.

La API permite a un cliente autorizado consultar las cuentas 2FA de un equipo y obtener sus códigos TOTP.

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

Usa únicamente HTTPS en producción. Las peticiones y respuestas están en formato JSON.

Autenticación

Cada llamada lleva un token Sanctum en la cabecera:

Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz
Accept: application/json

Crear un token desde la aplicación

Es la vía recomendada. En tu perfil, sección Tokens de API, elige los permisos y el periodo de validez; se vuelve a pedir la contraseña y el token solo se muestra una vez.

Crear un token por la API

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

El segundo factor es obligatorio, de una de estas formas:

  • cuenta protegida por una aplicación de autenticación: el código de seis dígitos en code, o un código de recuperación en recovery_code;

  • cuenta sin aplicación de autenticación: la primera llamada, sin code, no crea nada. Responde 409 y envía un código de seis dígitos por correo:

    {
      "message": "Te hemos enviado un código de seis dígitos por correo. Repite esta solicitud con ese código en confirmation_code.",
      "confirmation_required": true
    }
    

    Repite la misma petición con ese código en confirmation_code. Solo sirve una vez y caduca a los 15 minutos.

Respuesta:

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

Guarda este token como un secreto.

Permisos y duración

PermisoDa acceso a
secrets:listla lista de cuentas 2FA y el detalle de una cuenta
secrets:generateel código actual de una cuenta
teams:readlos equipos, sus miembros y el cambio de equipo activo
audit:readel registro de accesos (propietario del equipo)
integrations:managelas integraciones de mensajería (propietario del equipo)

Sin abilities, el token recibe los cinco permisos: pide solo los que necesite tu herramienta. expires_in_days vale 1, 7, 30 o 90, y 30 por defecto. Una cuenta tiene como máximo diez tokens activos; los tokens caducados se eliminan automáticamente y los demás se revocan desde el perfil.

Crear, modificar o eliminar secretos y equipos se hace en la aplicación: ningún token puede recibir esos derechos.

Equipo activo

Los códigos devueltos pertenecen siempre al equipo activo del usuario.

Listar los equipos accesibles:

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

Cambiar de equipo activo (permiso teams:read):

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

Listar las cuentas 2FA

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

Respuesta abreviada:

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

La semilla TOTP nunca se incluye en las respuestas.

Obtener un código

Usa el identificador devuelto por la lista:

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

Respuesta:

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

Cada generación queda registrada en el registro de accesos del equipo. No registres el código en el lado del cliente.

Registro de accesos

Reservado al propietario del equipo activo, con un token que tenga el permiso audit:read. El registro abarca el sitio, la API y los bots de mensajería.

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

Filtros opcionales:

ParámetroValores
secret_ididentificador de un secreto del equipo
actionlist, view o generate
channelweb, api, slack, discord o teams
limitde 1 a 500, 100 por defecto

Respuesta:

{
  "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 para un bot: el nombre y external_id son los que ha declarado la plataforma, sin una cuenta de Share Auth detrás. actor.deleted indica una cuenta eliminada desde entonces.
  • meta.visible_since es el inicio del periodo visible con el plan (7 días en Gratis, 90 en Team), null en Business. meta.hidden cuenta las entradas más antiguas, conservadas pero ocultas.

Errores

EstadoSignificado
401token ausente o no válido
403acceso denegado o secreto fuera del equipo activo
404recurso no encontrado
422datos no válidos, equipo ausente o código imposible de generar
429límite de 60 peticiones por minuto superado

Un error de validación suele tener este formato:

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

Conector MCP

El conector MCP ofrece a los asistentes de IA (ChatGPT, Codex, Claude y otros clientes MCP) dos herramientas: listar las cuentas 2FA del equipo y obtener el código actual. Nunca lee ni devuelve la semilla TOTP, y cada código obtenido aparece en el registro de accesos. Se autentica con un token limitado a secrets:list y secrets:generate.

El conector se describe en detalle en la página Agentes de IA (MCP). Su código es público en GitHub, como el de la skill 2FA para agentes.