Skip to main content

​
Overview

The Hitler API uses JWT (JSON Web Tokens) for authentication. There are two ways to obtain a token:
  1. Email/Password - Traditional login
  2. Slack OAuth - Sign in with Slack

​
Email/Password Authentication

​
Login

curl -X POST "https://api.hitler.app/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'
Response: 
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 604800,
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "employee",
    "organizationId": "org-uuid"
  }
}

​
Register

curl -X POST "https://api.hitler.app/api/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "secure-password-123",
    "name": "Jane Smith",
    "organizationId": "org-uuid"
  }'
Registration requires a valid organizationId. Organizations are created separately or via Slack OAuth.

​
Slack OAuth

​
Flow Overview

1. Frontend requests OAuth URL
2. User redirected to Slack
3. User authorizes
4. Slack redirects to callback
5. API exchanges code for tokens
6. JWT returned to frontend

​
Get OAuth URL

curl "https://api.hitler.app/api/auth/slack/url?returnUrl=https://app.hitler.app"
Response: 
{
  "url": "https://slack.com/oauth/v2/authorize?client_id=...",
  "state": "random-state-string",
  "callbackUrl": "https://api.hitler.app/api/auth/slack/callback",
  "type": "signin"
}

​
Callback

The callback is handled automatically. On success, the user is redirected to returnUrl with the token.

​
Using the Token

Include the token in the Authorization header: 
curl "https://api.hitler.app/api/auth/me" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

​
Token Refresh

Tokens expire after 7 days. Refresh before expiry: 
curl -X POST "https://api.hitler.app/api/auth/refresh" \
  -H "Authorization: Bearer YOUR_CURRENT_TOKEN"
Response: 
{
  "accessToken": "new-jwt-token...",
  "expiresIn": 604800,
  "user": { ... }
}

​
Get Current User

Verify a token and get user info: 
curl "https://api.hitler.app/api/auth/me" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response: 
{
  "id": "user-uuid",
  "email": "user@example.com",
  "name": "John Doe",
  "role": "employee",
  "organizationId": "org-uuid"
}

​
Token Structure

The JWT payload contains: 
{
  "sub": "user-uuid",
  "orgId": "organization-uuid",
  "role": "employee",
  "iat": 1642089600,
  "exp": 1642694400
}
FieldDescription
subUser ID
orgIdOrganization ID
roleUser role (employee, manager, admin)
iatIssued at timestamp
expExpiration timestamp

​
Error Responses

​
Invalid Credentials

{
  "statusCode": 401,
  "message": "Invalid credentials",
  "error": "Unauthorized"
}

​
Token Expired

{
  "statusCode": 401,
  "message": "Token expired",
  "error": "Unauthorized"
}

​
Email Already Registered

{
  "statusCode": 409,
  "message": "Email already registered",
  "error": "Conflict"
}

​
Security Best Practices

In browsers, use httpOnly cookies or secure storage. Never expose tokens in URLs or logs.
Implement proactive token refresh to avoid interruptions.
When you receive a 401, redirect to login or attempt refresh.
Always use HTTPS in production to protect tokens in transit.