MA
MachineAuth

Multi-Tenancy

MachineAuth supports organizations and teams for tenant isolation.

Organizations

An organization is a top-level tenant:

# Create organization
curl -X POST http://localhost:8080/api/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "slug": "acme",
    "owner_email": "admin@acme.com"
  }'

Response:

{
  "id": "org_abc123",
  "name": "Acme Corp",
  "slug": "acme",
  "owner_email": "admin@acme.com",
  "plan": "free",
  "created_at": "2026-03-01T12:00:00Z"
}

Teams

Teams are groups within an organization:

# Create team
curl -X POST http://localhost:8080/api/organizations/org_abc123/teams \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering",
    "description": "Backend services team"
  }'

Agent Organization Assignment

Assign agents to orgs and teams:

curl -X POST http://localhost:8080/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backend-agent",
    "organization_id": "org_abc123",
    "team_id": "team_xyz789",
    "scopes": ["read", "write"]
  }'

JWT tokens include org/team claims:

{
  "agent_id": "550e8400-...",
  "org_id": "org_abc123",
  "team_id": "team_xyz789",
  "scope": ["read", "write"]
}

API Keys

Organizations can have API keys for admin access:

# Create API key
curl -X POST http://localhost:8080/api/organizations/org_abc123/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-key",
    "expires_in": 86400
  }'

Response:

{
  "api_key": {
    "id": "key_123",
    "name": "production-key",
    "prefix": "mach_abc123",
    "is_active": true
  },
  "key": "mach_abc123def456..."
}

Use API key instead of JWT:

curl http://localhost:8080/api/verify \
  -H "Authorization: Bearer mach_abc123def456..."

Use Cases

| Scenario | Solution | |----------|----------| | SaaS product | Create org per customer | | Internal teams | Create org per department | | Multiple products | Create org per product |

Next Steps