Autenticação

Todas as requisições à API exigem um token Bearer no header Authorization. Os tokens são emitidos pelo endpoint de login e expiram após 1 ano.

Authorization: Bearer {token}

Login

POST /auth/login

Autentica um usuário com e-mail e senha. Retorna um token Bearer para chamadas subsequentes à 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"
  }'

Corpo da requisição

Headers

Resposta 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..."
  }
}

Respostas de erro

MFA (Autenticação em Dois Fatores)

Se o MFA estiver habilitado na conta, o endpoint de login retorna um desafio em vez de um token.

Etapa 1 — Login retorna o desafio MFA

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

O mfa_token é válido por 5 minutos.

Etapa 2 — Verificar o 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"
  }'

Retorna a mesma resposta 200 OK de um login padrão com access_token.

Atalho — Você também pode enviar o mfa_code diretamente no corpo da requisição inicial /auth/login para pular o fluxo em duas etapas, caso já tenha o código TOTP disponível.

Verificar autenticação

POST /auth/me

Retorna o perfil do usuário autenticado. Use para validar um token.

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

Resposta 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

Revoga o token atual e emite um novo. Use para rotação de tokens sem exigir que o usuário faça login novamente.

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

Resposta 200 OK

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

Após a renovação, o token anterior é imediatamente revogado. Atualize o token armazenado com o novo access_token.

Logout

POST /auth/logout

Revoga o token atual. O token não pode ser usado após esta chamada.

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

Resposta 200 OK

{
  "message": "Successful logout"
}

Resposta de erro

Se o token estiver ausente, inválido ou expirado, a API retorna 401 Unauthorized:

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

Referência de token

Boas práticas de segurança

• Nunca exponha tokens em código client-side ou repositórios públicos
• Use variáveis de ambiente para armazenar tokens nas suas aplicações
• Renove tokens periodicamente usando o endpoint /auth/refresh
• Use apenas HTTPS — a API rejeita requisições HTTP sem criptografia
• Trate o MFA — sempre verifique mfa_required: true nas respostas de login