Autenticación

Todas las solicitudes a la API requieren un token Bearer en el header Authorization. Los tokens se emiten a través del endpoint de login y expiran después de 1 año.

Authorization: Bearer {token}

Login

POST /auth/login

Autentica a un usuario con email y contraseña. Devuelve un token Bearer para las llamadas posteriores a la API.

curl -X POST https://services.gitscrum.com/auth/login \
  -H "Content-Type: application/json" \
  -H "X-Client-Type: api" \
  -d '{
    "email": "jane@acme.co",
    "password": "your-password"
  }'

Cuerpo de la solicitud

Headers

Respuesta 200 OK

{
  "data": {
    "companies": [
      {
        "slug": "acme-corp",
        "name": "Acme Corp",
        "logo": "https://cdn.gitscrum.com/logo.png"
      }
    ],
    "user": {
      "id": 1,
      "uuid": "user-uuid-123",
      "name": "Jane Smith",
      "username": "janesmith",
      "email": "jane@acme.co",
      "avatar": "https://avatar.url/jane.jpg",
      "headline": "Lead Developer",
      "timezone_name": "Europe/Lisbon",
      "language": "en"
    },
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1Q..."
  }
}

Respuestas de error

MFA (Autenticación de dos factores)

Si MFA está habilitado en la cuenta, el endpoint de login devuelve un desafío en lugar de un token.

Paso 1 — El login devuelve un desafío MFA

{
  "mfa_required": true,
  "mfa_token": "random-64-character-string",
  "message": "MFA verification required"
}

El mfa_token es válido durante 5 minutos.

Paso 2 — Verificar el código MFA

POST /auth/login/mfa-verify

curl -X POST https://services.gitscrum.com/auth/login/mfa-verify \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_token": "random-64-character-string",
    "mfa_code": "123456"
  }'

Devuelve la misma respuesta 200 OK que un login estándar con access_token.

Atajo — También puedes enviar mfa_code directamente en el cuerpo de la solicitud inicial /auth/login para omitir el flujo de dos pasos, si ya tienes el código TOTP disponible.

Verificar autenticación

POST /auth/me

Devuelve el perfil del usuario autenticado. Úsalo para validar un token.

curl -X POST https://services.gitscrum.com/auth/me \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Respuesta 200 OK

{
  "data": {
    "id": 1,
    "uuid": "user-uuid-123",
    "name": "Jane Smith",
    "username": "janesmith",
    "email": "jane@acme.co",
    "avatar": "https://avatar.url/jane.jpg",
    "headline": "Lead Developer",
    "timezone_name": "Europe/Lisbon",
    "language": "en"
  }
}

Renovar token

POST /auth/refresh

Revoca el token actual y emite uno nuevo. Úsalo para la rotación de tokens sin requerir que el usuario inicie sesión nuevamente.

curl -X POST https://services.gitscrum.com/auth/refresh \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Respuesta 200 OK

{
  "data": {
    "token_type": "Bearer",
    "access_token": "eyJ0eXAiOiJKV1Q..."
  }
}

Después de la renovación, el token anterior se revoca inmediatamente. Actualiza tu token almacenado con el nuevo access_token.

Logout

POST /auth/logout

Revoca el token actual. El token no puede usarse después de esta llamada.

curl -X POST https://services.gitscrum.com/auth/logout \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Respuesta 200 OK

{
  "message": "Successful logout"
}

Respuesta de error

Si el token falta, es inválido o ha expirado, la API devuelve 401 Unauthorized:

{
  "error": "Unauthorized",
  "message": "Invalid or expired token"
}

Referencia de tokens

Buenas prácticas de seguridad

• Nunca expongas tokens en código del lado del cliente o repositorios públicos
• Usa variables de entorno para almacenar tokens en tus aplicaciones
• Rota los tokens periódicamente usando el endpoint /auth/refresh
• Usa solo HTTPS — la API rechaza solicitudes HTTP sin cifrar
• Gestiona MFA — siempre verifica si mfa_required: true aparece en las respuestas de login