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 enrecovery_code;cuenta sin aplicación de autenticación: la primera llamada, sin
code, no crea nada. Responde409y 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
| Permiso | Da acceso a |
|---|---|
secrets:list | la lista de cuentas 2FA y el detalle de una cuenta |
secrets:generate | el código actual de una cuenta |
teams:read | los equipos, sus miembros y el cambio de equipo activo |
audit:read | el registro de accesos (propietario del equipo) |
integrations:manage | las 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ámetro | Valores |
|---|---|
secret_id | identificador de un secreto del equipo |
action | list, view o generate |
channel | web, api, slack, discord o teams |
limit | de 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.verifiedvalefalsepara un bot: el nombre yexternal_idson los que ha declarado la plataforma, sin una cuenta de Share Auth detrás.actor.deletedindica una cuenta eliminada desde entonces.meta.visible_sincees el inicio del periodo visible con el plan (7 días en Gratis, 90 en Team),nullen Business.meta.hiddencuenta las entradas más antiguas, conservadas pero ocultas.
Errores
| Estado | Significado |
|---|---|
401 | token ausente o no válido |
403 | acceso denegado o secreto fuera del equipo activo |
404 | recurso no encontrado |
422 | datos no válidos, equipo ausente o código imposible de generar |
429 | lí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.