API pública — Share Auth

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

Crea un token Sanctum:

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",
    "code":"123456"
  }'

El campo code solo es obligatorio si la cuenta protege su acceso con 2FA. recovery_code puede sustituirlo.

Respuesta:

{
  "token": "1|abcdefghijklmnopqrstuvwxyz",
  "user": {
    "id": 12,
    "name": "Alice",
    "email": "[email protected]"
  }
}

Guarda este token como un secreto y envíalo después en la cabecera:

Authorization: Bearer 1|abcdefghijklmnopqrstuvwxyz
Accept: application/json

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:

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.

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 listo para usar con ChatGPT, Codex, Claude y otros clientes MCP está documentado en mcp-server/README.md, en el repositorio del proyecto.