Machine Users

Machine users provide service account authentication for backend services and applications to communicate with the Manager API.

Overview

Machine users are tenant-scoped service accounts designed for:

• Backend Services - Authenticate microservices and APIs
• Automated Systems - Integration with automated workflows
• Service-to-Service - Enable secure service communication
• Trigger Callbacks - Receive trigger execution requests
• Endpoint Access - Control access to specific endpoints

Unlike Personal Access Tokens which are user-scoped, machine users operate at the tenant level and support both Bearer token and Basic authentication.

Authentication Methods

Bearer Token Authentication

Recommended for production use. Tokens are generated by the Manager and use PBKDF2 hashing.

HTTP Header:

Authorization: Bearer <token>

Example:

curl -H "Authorization: Bearer muser_abc123def456..." \
  https://manager.example.com/api/machine/check

Basic Authentication

Supports username/password authentication for compatibility with legacy systems.

HTTP Header:

Authorization: Basic <base64(username:password)>

Example:

curl -u "backend-service:secret-password" \
  https://manager.example.com/api/machine/check

Creating Machine Users

With Auto-Generated Token (Recommended)

Via UI:

1. Navigate to Tenants → Select tenant
2. Click Machine Users tab
3. Click Create Machine User
4. Fill in details:
   • Name - Service identifier (e.g., "Payment Service")
   • Username - Unique identifier for the service
   • Generate Token - Check this option
5. Click Create
6. Copy the token immediately - shown only once

Via API:

mutation {
  createMachineUserWithCredentials(
    tenantId: "tenant-uuid"
    input: {
      name: "Payment Service"
      username: "payment-service"
      hashedKey: "__GENERATE_TOKEN__"
      enabled: true
    }
  ) {
    generatedToken
    machineUser {
      id
      username
      tokenPrefix
    }
  }
}

Token Generation

Use hashedKey: "__GENERATE_TOKEN__" to auto-generate a secure Bearer token. The plaintext token is only returned once during creation.

With Basic Authentication

Via API:

mutation {
  createMachineUserWithCredentials(
    tenantId: "tenant-uuid"
    input: {
      name: "Legacy Service"
      username: "legacy-service"
      hashedKey: "<password-hash>"
      enabled: true
    }
  ) {
    plaintextPassword
    machineUser {
      id
      username
    }
  }
}

For Basic auth, provide a pre-hashed password or the plaintext password (which will be hashed by the Manager).

Managing Machine Users

Listing Machine Users

Via UI: Navigate to Tenants → Select tenant → Machine Users tab

Via API:

query {
  machineUsers(
    tenant: "tenant-uuid"
    filters: []
    order: { field: "name", direction: ASC }
    pagination: { limit: 20, offset: 0 }
  ) {
    id
    name
    username
    enabled
    tokenPrefix
    createdAt
  }
}

Enabling/Disabling

Disable a machine user to immediately prevent authentication without deleting the record.

Via UI:

1. Navigate to Machine Users
2. Find the machine user
3. Toggle the Enabled switch

Via API:

mutation {
  updateMachineUser(id: "machine-user-uuid", input: { enabled: false }) {
    id
    enabled
  }
}

Deleting Machine Users

Via UI:

1. Navigate to Machine Users
2. Find the machine user to delete
3. Click Delete
4. Confirm the action

Via API:

mutation {
  deleteMachineUser(id: "machine-user-uuid")
}

WARNING

Deleting a machine user immediately invalidates all tokens and breaks any services using that machine user for authentication.

Endpoint Access Control

Machine users can be granted access to specific endpoints, providing fine-grained authorization control.

Granting Endpoint Access

Via UI:

1. Navigate to Applications → Endpoints
2. Select an endpoint
3. Click Machine User Access tab
4. Select machine users to grant access
5. Toggle Enabled for each assignment

Via API:

mutation {
  createMachineUser2Endpoint(
    input: {
      machineUserID: "machine-user-uuid"
      endpointID: "endpoint-uuid"
      enabled: true
    }
  ) {
    id
    enabled
  }
}

Revoking Endpoint Access

Via UI:

1. Navigate to endpoint's Machine User Access
2. Toggle Enabled off for the machine user
3. Or click Remove to delete the assignment

Via API:

mutation {
  deleteMachineUser2Endpoint(id: "relation-uuid")
}

Backend Registration

Machine users can register backend services to receive trigger execution callbacks.

Registering a Backend

REST API:

curl -X POST https://manager.example.com/api/machine/register-backend \
  -H "Authorization: Bearer <machine-user-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Processing Service",
    "callbackUrl": "https://payment.example.com/triggers/callback",
    "description": "Handles payment processing triggers"
  }'

Response:

{
  "id": "backend-uuid",
  "name": "Payment Processing Service",
  "callbackUrl": "https://payment.example.com/triggers/callback",
  "machineUserId": "machine-user-uuid"
}

Receiving Trigger Callbacks

When triggers execute, the Manager sends POST requests to registered callback URLs:

Callback Request:

{
  "triggerId": "trigger-uuid",
  "triggerName": "Hourly Payment Processing",
  "executionTime": "2025-12-01T10:00:00Z",
  "application": {
    "id": "app-uuid",
    "name": "Payment App",
    "slug": "payment-app"
  },
  "tenant": {
    "id": "tenant-uuid",
    "name": "Customer A",
    "slug": "customer-a"
  }
}

Expected Response:

{
  "status": "success",
  "message": "Processing completed"
}

See Triggers & Automation for details on the trigger system.

REST API Endpoints

Validate Machine User

Endpoint: POST /api/validate-machine-user

Purpose: Validates machine user credentials (used internally by Proxy)

Request:

{
  "username": "payment-service",
  "token": "token-or-password"
}

Response:

{
  "valid": true,
  "tenantId": "tenant-uuid",
  "machineUserId": "machine-user-uuid"
}

Check Authentication

Endpoint: GET /api/machine/check

Purpose: Verifies current machine user authentication

Headers:

Authorization: Bearer <token>

Response:

{
  "authenticated": true,
  "machineUserId": "machine-user-uuid",
  "tenantId": "tenant-uuid"
}

Token Prefix

For Bearer authentication, the first few characters of the token are stored as a prefix for searchability:

Example:

• Full token: muser_abc123def456ghi789...
• Stored prefix: muser_abc

This allows you to identify tokens in the UI without exposing the full token value.

Best Practices

Security

• Use Bearer tokens for production environments
• Rotate tokens regularly - Create new machine users and retire old ones
• Limit endpoint access - Grant only necessary endpoint permissions
• Monitor usage - Track which services use which machine users
• Disable unused accounts - Turn off machine users that are no longer needed

Organization

• Descriptive names - Use clear names that identify the service
• One service, one user - Create separate machine users for each service
• Document usage - Maintain records of what each machine user is for
• Environment separation - Use different machine users for dev/staging/production

Operational

• Test authentication - Verify tokens work before deploying services
• Handle errors gracefully - Implement retry logic for authentication failures
• Log authentication events - Track successful and failed authentication attempts
• Plan for rotation - Design services to support credential rotation

Troubleshooting

Authentication Failures

Check:

• Machine user is Enabled
• Token/password is correct and complete
• Authorization header format is correct
• Machine user belongs to the correct tenant
• Network connectivity to Manager API

Endpoint Access Denied

Verify:

• Machine user has been granted access to the endpoint
• The machine user-to-endpoint relationship is Enabled
• Endpoint itself is Enabled
• Request is using the correct machine user credentials

Backend Registration Fails

Possible causes:

• Invalid machine user token
• Callback URL is not accessible
• Network/firewall blocking outbound connections from Manager
• Invalid JSON in registration request

Token Not Working After Creation

Common issues:

• Token was not copied correctly (check for extra spaces)
• Using wrong authentication method (Bearer vs Basic)
• Machine user was disabled after creation
• Token prefix shown instead of full token

Comparison with Personal Access Tokens

Feature	Machine Users	Personal Access Tokens
Scope	Tenant-level	User-level
Auth Methods	Bearer + Basic	Bearer only
Purpose	Service accounts	Personal automation
Expiration	No expiration	Optional expiration
Endpoint Access	Configurable	Full user permissions
Created By	Admins	Individual users

Use Machine Users for:

• Production backend services
• Service-to-service communication
• Trigger callback handling
• Tenant-scoped operations

Use PATs for:

• Personal CLI tools and scripts
• Development and testing
• User-specific automation
• Temporary access

See Personal Access Tokens for user-level authentication.

API Reference

Complete machine user management operations:

• Create Machine User
• List Machine Users
• Update Machine User
• Delete Machine User
• Endpoint Access Control

See the full API Reference for all operations.