Authentication

IRA FORCE uses JWT (JSON Web Tokens) for API authentication. All API requests must include a valid access token in the Authorization header.

Overview

The authentication system supports multiple flows depending on your use case: OAuth 2.0 for user authentication, API keys for server-to-server communication, and mobile-specific flows for the field workforce app.

API Keys

Long-lived tokens for server-to-server integrations and automated systems.

OAuth 2.0

Standard OAuth flows for web applications and third-party integrations.

Mobile Auth

Biometric and PIN-based authentication for the IRA FORCE mobile apps.

SSO

Enterprise Single Sign-On via SAML 2.0 and OpenID Connect.

API Keys

API keys are the simplest way to authenticate with the IRA FORCE API. They're ideal for backend services, CI/CD pipelines, and automated integrations.

Security Warning Never expose API keys in client-side code or public repositories. Use environment variables.

Creating an API Key

Generate API keys from the IRA FORCE admin dashboard or via the API:

cURL

curl -X POST https://api.iraforce.cloud/v1/api-keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Integration",
    "scopes": ["employees:read", "attendance:write", "schedules:read"],
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

Using API Keys

Include the API key in the X-API-Key header:

cURL

curl https://api.iraforce.cloud/v1/employees \
  -H "X-API-Key: ira_live_sk_abc123xyz789"

JWT Authentication

For user-facing applications, authenticate using JWT tokens obtained through the login flow:

JavaScript

// Login to obtain tokens
const response = await fetch('https://api.iraforce.cloud/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@company.com',
    password: 'securepassword123'
  })
});

const { accessToken, refreshToken, expiresIn } = await response.json();

// Use the access token for API requests
const employees = await fetch('https://api.iraforce.cloud/v1/employees', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

Token Lifecycle

Token Type	Lifetime	Usage
`accessToken`	15 minutes	API requests
`refreshToken`	7 days	Obtain new access tokens
`apiKey`	Until revoked	Server-to-server

Refreshing Tokens

When access tokens expire, use the refresh token to obtain a new pair:

JavaScript

const response = await fetch('https://api.iraforce.cloud/v1/auth/refresh', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    refreshToken: 'your-refresh-token'
  })
});

const { accessToken, refreshToken: newRefreshToken } = await response.json();

Permission Scopes

API keys and OAuth tokens can be restricted to specific scopes:

Available Scopes

# Core Resources
employees:read       # View employee data
employees:write      # Create/update employees
schedules:read       # View schedules
schedules:write      # Manage schedules
attendance:read      # View attendance records
attendance:write     # Clock in/out, edit timesheets

# Security Operations
incidents:read       # View incident reports
incidents:write      # Create/manage incidents
patrols:read         # View patrol data
patrols:write        # Manage guard tours

# Administrative
admin:users          # Manage system users
admin:settings       # Configure organization settings
admin:billing        # Access billing information

Best Practice Always request the minimum scopes needed for your integration. This follows the principle of least privilege.

Error Handling

Authentication errors return standard HTTP status codes:

JSON

// 401 Unauthorized - Invalid or expired token
{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The access token is invalid or has expired",
    "hint": "Refresh your token using the /auth/refresh endpoint"
  }
}

// 403 Forbidden - Insufficient permissions
{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This action requires the 'employees:write' scope",
    "requiredScopes": ["employees:write"]
  }
}