Authentication

All API requests require a Bearer token in the Authorization header. Tokens are issued via the login endpoint and expire after 1 year.

Authorization: Bearer {token}

Login

POST /auth/login

Authenticates a user with email and password. Returns a Bearer token for subsequent API calls.

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"
  }'

Request body

Headers

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

Error responses

MFA (Two-Factor Authentication)

If MFA is enabled on the account, the login endpoint returns a challenge instead of a token.

Step 1 — Login returns MFA challenge

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

The mfa_token is valid for 5 minutes.

Step 2 — Verify the MFA code

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"
  }'

Returns the same 200 OK response as a standard login with access_token.

Shortcut — You can also pass mfa_code directly in the initial /auth/login request body to skip the two-step flow, if you already have the TOTP code available.

Verify authentication

POST /auth/me

Returns the authenticated user profile. Use this to validate a token.

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

Response 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"
  }
}

Refresh token

POST /auth/refresh

Revokes the current token and issues a new one. Use this for token rotation without requiring the user to log in again.

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

Response 200 OK

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

After refresh, the previous token is immediately revoked. Update your stored token with the new access_token.

Logout

POST /auth/logout

Revokes the current token. The token cannot be used after this call.

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

Response 200 OK

{
  "message": "Successful logout"
}

Error response

If the token is missing, invalid, or expired, the API returns 401 Unauthorized:

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

Token reference

Security best practices

• Never expose tokens in client-side code or public repositories
• Use environment variables to store tokens in your applications
• Rotate tokens periodically using the /auth/refresh endpoint
• Use HTTPS only — the API rejects plain HTTP requests
• Handle MFA — always check for mfa_required: true in login responses