Identity and Access Management (IAM) in Hantera provides a comprehensive system for managing identities, roles, and permissions. IAM is the foundation for authentication and authorization across all Hantera services.

TIP

For detailed API endpoint documentation, see the OpenAPI browser. This page focuses on domain concepts and integration patterns.

What is IAM?

IAM manages three core concepts:

1. Identities - Who can access the system (principals and clients)
2. Roles - What permissions identities have
3. Sessions - Active authentication sessions

IAM provides REST APIs for creating and managing these entities, while the Graph API provides read access for querying identities.

Identity Types

Hantera supports three types of identities:

Principal

A principal represents a human identity that authenticates with Hantera.

Key characteristics:

• Email address (used as username, must be unique)
• Password or OAuth authentication
• Can be assigned multiple roles
• Can be temporarily suspended
• Dynamic properties for custom data

When to use:

• Portal users (administrators, staff)
• Customer accounts
• Partner or vendor users
• Any human that needs to log in

Learn more: Principals Documentation

Client

A client represents an application or service identity for OAuth and API access.

Key characteristics:

• OAuth configuration (redirect URIs, grant types, scopes)
• Client secret authentication
• No password-based login
• System clients are protected from modification

When to use:

• Third-party integrations
• Mobile or web applications
• Service-to-service communication
• Webhook consumers

Learn more: Clients Documentation

Roles and Permissions

Built-in System Roles

Hantera provides built-in roles that use the system: namespace:

system:owner

Full administrative access to all Hantera resources and operations.

Capabilities:

• Manage all identities, roles, and permissions
• Access all resources without restrictions
• Configure system settings
• Perform destructive operations

WARNING

Grant system:owner only to fully trusted administrators. This role bypasses all authorization checks.

system:portal:full

Complete access to the Hantera Portal and portal-managed resources.

Capabilities:

• Access all portal features
• Manage orders, customers, products
• View analytics and reports
• Configure portal settings

Typical users:

• Portal administrators
• Customer service managers
• Operations staff

Custom Roles

You can define custom roles with any namespace except system:.

Role naming pattern:

{namespace}:{capability}

Examples:

• store:manager - Store management permissions
• support:agent - Customer support access
• warehouse:operator - Warehouse operations
• reporting:viewer - Read-only reporting access

Custom role definition:

{
  "key": "support:agent",
  "description": "Customer support representative",
  "acl": {
    "entries": [
      { "resource": "actors", "permission": "*" },
      { "resource": "graph", "permission": "*" },
      { "resource": "registry", "permission": "read" }
    ]
  }
}

Role-Based Categorization

Roles serve dual purposes in Hantera:

1. Authorization - Define what an identity can do
2. Categorization - Group identities by function

This means you can filter identities by role prefix to create semantic groups:

// Get all portal users
GET /resources/iam/principals?rolePrefix=system:portal:

// Get all support agents
GET /resources/iam/principals?rolePrefix=support:

// Get all store managers
GET /resources/iam/principals?rolePrefix=store:

This pattern eliminates the need for separate "user type" fields while ensuring categorization always reflects actual permissions.

Authorization Model

Required Permissions

IAM operations require specific permissions:

Principal management:

iam/principals:read     # List and get principals
iam/principals:write    # Create and update principals
iam/principals:delete   # Delete principals

Client management:

iam/clients:read        # List and get clients
iam/clients:write       # Create and update clients
iam/clients:delete      # Delete clients

Role management:

iam/roles:read          # List and get roles
iam/roles:write         # Create and update custom roles
iam/roles:delete        # Delete custom roles

Safe Updates with ETags

IAM APIs use ETags to prevent conflicting updates when multiple users modify the same identity.

Usage:

# 1. Get the identity (response includes ETag header)
GET /resources/iam/principals/{id}

# 2. Update with If-Match header using the ETag
PUT /resources/iam/principals/{id}
If-Match: "etag-value-from-step-1"
{
  "properties": { ... }
}

If someone else modified the identity between your GET and PUT, the request will fail with 409 Conflict, preventing you from accidentally overwriting their changes.

TIP

Always include the If-Match header when updating identities to ensure safe concurrent modifications.

API Endpoints Summary

IAM provides REST endpoints organized by resource type:

• /resources/iam/principals/* - Principal management (details)
• /resources/iam/clients/* - Client management (details)
• /resources/iam/roles/* - Role management

For complete endpoint documentation, request/response formats, and error codes, see the HTTP API Reference.

Quick Start Examples

Creating a Portal User

PUT /resources/iam/principals/{userId}
{
  "properties": {
    "name": "John Admin",
    "email": "[email protected]"
  },
  "roles": ["system:portal:full"]
}

Then generate a temporary password and send via email using the Sendings API.

Creating an OAuth Client

PUT /resources/iam/clients/{clientId}
{
  "properties": {
    "name": "Mobile App",
    "redirectUris": ["myapp://callback"],
    "grantTypes": ["authorization_code", "refresh_token"]
  },
  "roles": []
}

Querying Identities

Use the Graph API to query identities:

POST /resources/graph/query
{
  "resource": "identity",
  "filters": [
    { "field": "roles", "op": "contains", "value": "system:portal:full" }
  ],
  "limit": 50
}

Common Workflows

User Onboarding

1. Create principal

   PUT /resources/iam/principals/{id}

2. Assign roles

   PUT /resources/iam/principals/{id}/roles

3. Generate temporary password

   POST /resources/iam/principals/{id}/password/reset

4. Send welcome email Use Sendings API to send credentials

5. User logs in and changes password

   POST /resources/me/password

Application Integration

1. Create OAuth client

   PUT /resources/iam/clients/{id}

2. Generate client secret

   POST /resources/iam/clients/{id}/secrets

3. Configure application Use client ID and secret in your OAuth flow

4. Assign necessary roles

   PUT /resources/iam/clients/{id}/roles

Next Steps

• Principals Documentation - Deep dive into user management
• Clients Documentation - OAuth clients and service accounts
• Access Control - Permission patterns and best practices
• Graph API - Querying identities
• HTTP API Reference - Complete endpoint documentation

Related Resources

• Identity Graph Node - Query identities via Graph
• Me Endpoint - Current user information and password management
• Sendings API - Send emails (for password resets)
• Authentication Guide - How authentication works in Hantera