Skip to main content

IAM Service: Core API Workflows

This guide walks you through the fundamental API workflows for the iam-service. It assumes you have a running local environment as described in the Getting Started guide.

Prerequisites​

These examples use jq, a command-line JSON processor, to easily extract values from API responses. You can install it with your system's package manager (e.g., brew install jq, apt-get install jq).

Workflow 1: Create a Tenant​

A Tenant is the top-level container for all resources, representing a single customer or organization. Creating a tenant is the first step for any new entity.

We will create a tenant and store its unique ID in an environment variable for use in subsequent steps.

export TENANT_ID=$(curl -s -X POST http://localhost:1111/api/iam/tenants \
  -H "Content-Type: application/json" \
  -d '{"name": "MegaCorp", "slug": "megacorp"}' | jq -r '.id')

echo "New Tenant ID: $TENANT_ID"

This command sends a POST request to create the tenant and pipes the JSON response to jq, which extracts the id field.

Workflow 2: Create a User​

After a user has been created in the upstream IdP, you must create a corresponding user entity for them in the iam-service. This links the upstream user to a Citadel tenant.

This command uses the $TENANT_ID and an example IDP_USER_ID to create the mapping.

# In a real scenario, this ID would come from the upstream IdP after user creation.
export IDP_USER_ID="auth0|65b91a8b1234567890abcdef"

export USER_ID=$(curl -s -X POST "http://localhost:1111/api/iam/tenants/$TENANT_ID/users" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jdoe@example.com",
    "name": "John Doe",
    "idp_user_id": "$IDP_USER_ID"
  }' | jq -r '.id')

echo "New User ID: $USER_ID"

Workflow 3: Assign Attributes (ABAC)​

The IAM service uses Attribute-Based Access Control (ABAC). You can assign custom attributes to users, which are then evaluated by policies.

curl -s -X POST "http://localhost:1111/api/iam/tenants/$TENANT_ID/users/$USER_ID/attributes" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "roles",
    "value": "[\"admin\"]"
  }'

Workflow 4: Verify Tenant Details​

You can retrieve the details of the tenant we created earlier to verify the data.

curl -s -X GET "http://localhost:1111/api/iam/tenants/$TENANT_ID" | jq