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 <machine-user-token>" \
  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)>

Bearer Only Endpoints

The Manager's /api/machine/* and /esb/* endpoints accept Bearer tokens only. Basic-auth machine users are validated by the proxy (via the Manager's credential-validation endpoint) when calling applications behind the proxy.

Creating Machine Users

With Auto-Generated Token (Recommended)

Via UI:

1. Navigate to Tenants → Select tenant
2. Open the Machine Users page
3. Click Create
4. Fill in details:
   • Name - Service identifier (e.g., "Payment Service")
   • Auth Type - Select Bearer token
   • Enabled - Toggle on
5. Click Save
6. Copy the token immediately - it is shown only once

Via API:

mutation {
  createMachineUserWithCredentials(
    tenantId: "tenant-uuid"
    input: {
      name: "Payment Service"
      username: "Bearer"
      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. For Bearer machine users the username is managed by the Manager (it is replaced with an internal Bearer:<prefix> identifier).

With Basic Authentication

Via API:

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

For Basic auth, pass the plaintext password in hashedKey; the Manager hashes it (PBKDF2) before storing and echoes it back once in plaintextPassword. Usernames must be unique within the tenant.

Managing Machine Users

Listing Machine Users

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

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 the application's Endpoints page
2. Select an endpoint
3. Open the endpoint's Users page
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 the endpoint's Users page
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 '{
    "application_id": "550e8400-e29b-41d4-a716-446655440000",
    "callback_url": "https://payment.example.com/triggers/callback",
    "version": "1.0.0"
  }'

Response:

{
  "success": true,
  "registered_id": "backend-uuid",
  "token": "generated-bearer-token-for-callbacks",
  "message": "Backend registered successfully",
  "tenant_id": "tenant-uuid",
  "application_id": "550e8400-e29b-41d4-a716-446655440000"
}

The returned token is what the Manager uses to authenticate its trigger callbacks to your backend — store it and verify it on incoming callback requests.

Receiving Trigger Callbacks

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

Callback Request:

{
  "trigger_id": "trigger-uuid",
  "trigger_name": "Hourly Payment Processing",
  "cron_expression": "0 0 * * * *",
  "run_key": "hourly-payment",
  "executed_at": "2025-12-01T10:00:00Z"
}

The callback carries an Authorization: Bearer <token> header with the token returned at registration. Application/tenant context can be inferred from your registration.

Expected Response:

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

See Triggers & Automation for details on the trigger system.

REST API Endpoints

Credential Validation (Proxy)

Endpoint: POST /api/validate-proxy-auth

Purpose: Validates PAT and machine user credentials (Bearer or Basic). This endpoint is called by the Proxy and requires the proxy shared secret; it is not intended for direct client use.

Check Authentication

Endpoint: GET /api/machine/check

Purpose: Verifies current machine user authentication

Headers:

Authorization: Bearer <token>

Response:

{
  "authenticated": true,
  "machine_user_id": "machine-user-uuid",
  "tenant_id": "tenant-uuid"
}

Token Prefix

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

Example:

• Full token: X7f3kQ9pL2mN8rT5vW1z... (43-character random token)
• Stored prefix: X7f3kQ9pL2mN

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.