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 '{"company_name": "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 Policy Mapping​

After a user has been created in the upstream IdP, you must create a corresponding policy object 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"

curl -s -X POST "http://localhost:1111/api/iam/tenants/$TENANT_ID/users" \
  -H "Content-Type: application/json" \
  -d '{
    "idp_user_id": "$IDP_USER_ID"
  }' | jq

You will receive a JSON response containing the details of the newly created user policy, including its internal Citadel ID.

Workflow 3: Create an API Client​

API clients are used for machine-to-machine (M2M) authentication. After the iam-service provisions a client in the upstream IdP, that client can be used by other services or scripts to obtain access tokens.

The client creation endpoint is a top-level administrative action that requires the tenant_id in the request body. Let's create a client and capture its credentials.

CLIENT_CREDENTIALS=$(curl -s -X POST "http://localhost:1111/api/iam/clients" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reporting Service Client",
    "tenant_id": "$TENANT_ID",
    "redirect_uris": ["http://localhost:3000/callback"]
  }')

export CLIENT_ID=$(echo $CLIENT_CREDENTIALS | jq -r '.clientId')
export CLIENT_SECRET=$(echo $CLIENT_CREDENTIALS | jq -r '.clientSecret')

echo "Client ID: $CLIENT_ID"
# The client secret is only returned on creation. Store it securely.
echo "Client Secret: (hidden)"

The response for this request is the only time the clientSecret is ever shown.

Workflow 4: Update a Client​

You can modify an existing client's properties, such as its name or redirect URIs, using a PATCH request to its canonical /:client_id endpoint.

# We use the $CLIENT_ID captured in the previous step.
curl -s -X PATCH "http://localhost:1111/api/iam/clients/$CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Reporting Client Name",
    "redirect_uris": ["http://localhost:3000/callback", "https://new-app.com/callback"]
  }'

echo "Client $CLIENT_ID updated."

Workflow 5: Delete a Client​

You can delete a client using a DELETE request. This is an irreversible action.

# We use the $CLIENT_ID captured previously.
curl -s -X DELETE "http://localhost:1111/api/iam/clients/$CLIENT_ID"

echo "Client $CLIENT_ID deleted."

Next Steps​

You now have a fully provisioned tenant with a user and an API client. The iam-service has provisioned this client in the upstream Identity Provider (IdP).

The next step is to use the clientId and clientSecret to perform an OAuth 2.0 flow (e.g., Client Credentials Grant) directly against the upstream IdP's token endpoint. The access token returned by the IdP can then be used to call other services in the Citadel platform.