Create users — POST /v1/iam/users

Adds a person to your organization.

POST /v1/iam/users

IAM → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/iam/users`
Method	`POST`
Operation	`post_iam_users`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Adds a person to your organization. Send a password and it becomes the one they sign in with; it is hashed before it is stored and never comes back in any response.

The username is checked against the same rule every account in the Hanzo Cloud is held to, whichever way it was created — this call, password signup, a social sign-in, or SCIM — so a name accepted here works everywhere.

A name already taken in your organization is refused rather than overwritten.

Request

219 fields, body application/json (required).

Field	In	Type	Required	Description
`password`	body	string	—
`user`	body	iam.User	—
`user.accessKey`	body	string	—	API credentials.
`user.accessSecret`	body	string	—
`user.accessSecretHash`	body	string	—
`user.accessToken`	body	string	—
`user.address`	body	string[]	—
`user.addresses`	body	iam.Address[]	—
`user.addresses[].city`	body	string	—
`user.addresses[].line1`	body	string	—
`user.addresses[].line2`	body	string	—
`user.addresses[].region`	body	string	—
`user.addresses[].state`	body	string	—
`user.addresses[].tag`	body	string	—
`user.addresses[].zipCode`	body	string	—
`user.adfs`	body	string	—
`user.affiliation`	body	string	—
`user.alipay`	body	string	—
`user.amazon`	body	string	—
`user.apple`	body	string	—
`user.applicationScopes`	body	iam.ConsentRecord[]	—
`user.applicationScopes[].application`	body	string	—
`user.applicationScopes[].grantedScopes`	body	string[]	—
`user.auth0`	body	string	—
`user.avatar`	body	string	—
`user.avatarType`	body	string	—
`user.azuread`	body	string	—
`user.azureadb2c`	body	string	—
`user.baidu`	body	string	—
`user.balance`	body	number (double)	—	Balance mirrors v1 for lossless migration but is authoritative in Commerce (billing.hanzo.ai), not here — do not write it from IAM.
`user.balanceCredit`	body	number (double)	—
`user.balanceCurrency`	body	string	—
`user.battlenet`	body	string	—
`user.bilibili`	body	string	—
`user.bio`	body	string	—
`user.birthday`	body	string	—
`user.bitbucket`	body	string	—
`user.box`	body	string	—
`user.cart`	body	iam.CartItem[]	—
`user.cart[].displayName`	body	string	—
`user.cart[].name`	body	string	—
`user.cart[].owner`	body	string	—
`user.cart[].price`	body	number (double)	—
`user.cart[].quantity`	body	integer (int64)	—
`user.cloudfoundry`	body	string	—
`user.countryCode`	body	string	—
`user.createdAt`	body	string (date-time)	—
`user.createdIp`	body	string	—	Sign-in provenance.
`user.createdTime`	body	string	—
`user.currency`	body	string	—
`user.custom`	body	string	—
`user.custom2`	body	string	—
`user.custom3`	body	string	—
`user.custom4`	body	string	—
`user.custom5`	body	string	—
`user.custom6`	body	string	—
`user.custom7`	body	string	—
`user.custom8`	body	string	—
`user.custom9`	body	string	—
`user.custom10`	body	string	—
`user.dailymotion`	body	string	—
`user.deezer`	body	string	—
`user.deleted`	body	boolean	—
`user.deletedTime`	body	string	—
`user.digitalocean`	body	string	—
`user.dingtalk`	body	string	—
`user.discord`	body	string	—
`user.displayName`	body	string	—	Profile.
`user.douyin`	body	string	—
`user.dropbox`	body	string	—
`user.education`	body	string	—
`user.email`	body	string	—
`user.emailVerified`	body	boolean	—
`user.eveonline`	body	string	—
`user.externalId`	body	string	—
`user.faceIds`	body	iam.FaceId[]	—
`user.faceIds[].faceIdData`	body	number (double)[]	—
`user.faceIds[].imageUrl`	body	string	—
`user.faceIds[].name`	body	string	—
`user.facebook`	body	string	—
`user.firstName`	body	string	—
`user.fitbit`	body	string	—
`user.gender`	body	string	—
`user.gitea`	body	string	—
`user.gitee`	body	string	—
`user.github`	body	string	—	Linked federated-identity subjects, one column per connector (v1 parity).
`user.gitlab`	body	string	—
`user.google`	body	string	—
`user.hash`	body	string	—
`user.heroku`	body	string	—
`user.homepage`	body	string	—
`user.iam`	body	string	—
`user.id`	body	string	—	Id is the user's STABLE OPAQUE identifier — the value the OIDC `sub` claim carries.
`user.idCard`	body	string	—
`user.idCardType`	body	string	—
`user.influxcloud`	body	string	—
`user.infoflow`	body	string	—
`user.instagram`	body	string	—
`user.intercom`	body	string	—
`user.invitation`	body	string	—
`user.invitationCode`	body	string	—
`user.ipWhitelist`	body	string	—
`user.isAdmin`	body	boolean	—
`user.isDefaultAvatar`	body	boolean	—	State flags.
`user.isDeleted`	body	boolean	—
`user.isForbidden`	body	boolean	—
`user.isOnline`	body	boolean	—
`user.isVerified`	body	boolean	—
`user.kakao`	body	string	—
`user.karma`	body	integer (int64)	—
`user.kwai`	body	string	—
`user.language`	body	string	—
`user.lark`	body	string	—
`user.lastChangePasswordTime`	body	string	—
`user.lastName`	body	string	—
`user.lastSigninIp`	body	string	—
`user.lastSigninTime`	body	string	—
`user.lastSigninWrongTime`	body	string	—
`user.lastfm`	body	string	—
`user.ldap`	body	string	—
`user.line`	body	string	—
`user.linkedin`	body	string	—
`user.location`	body	string	—
`user.mailru`	body	string	—
`user.managedAccounts`	body	iam.ManagedAccount[]	—
`user.managedAccounts[].application`	body	string	—
`user.managedAccounts[].signinUrl`	body	string	—
`user.managedAccounts[].username`	body	string	—
`user.meetup`	body	string	—
`user.mfaAccounts`	body	iam.MfaAccount[]	—
`user.mfaAccounts[].accountName`	body	string	—
`user.mfaAccounts[].issuer`	body	string	—
`user.mfaAccounts[].origin`	body	string	—
`user.mfaEmailEnabled`	body	boolean	—
`user.mfaItems`	body	iam.MfaItem[]	—
`user.mfaItems[].name`	body	string	—
`user.mfaItems[].rule`	body	string	—
`user.mfaPhoneEnabled`	body	boolean	—
`user.mfaPushEnabled`	body	boolean	—
`user.mfaPushProvider`	body	string	—
`user.mfaPushReceiver`	body	string	—
`user.mfaRadiusEnabled`	body	boolean	—
`user.mfaRadiusProvider`	body	string	—
`user.mfaRadiusUsername`	body	string	—
`user.mfaRememberDeadline`	body	string	—
`user.mfaRememberDigest`	body	string	—	MfaRememberDigest is the digest of the token held by the ONE browser the deadline above applies to.
`user.microsoftonline`	body	string	—
`user.multiFactorAuths`	body	iam.MfaProps[]	—
`user.multiFactorAuths[].countryCode`	body	string	—
`user.multiFactorAuths[].enabled`	body	boolean	—
`user.multiFactorAuths[].isPreferred`	body	boolean	—
`user.multiFactorAuths[].mfaRememberInHours`	body	integer (int64)	—
`user.multiFactorAuths[].mfaType`	body	string	—
`user.multiFactorAuths[].url`	body	string	—
`user.name`	body	string	—
`user.nameKey`	body	string	—	NameKey is Fold(Name), derived on every save (BeforeCreate, BeforeUpdate) and on every open for a row saved without it (store.Prepare): the indexed key a case-insensitive username lookup reads (store.GetUserByName).
`user.naver`	body	string	—
`user.needUpdatePassword`	body	boolean	—
`user.nextcloud`	body	string	—
`user.okta`	body	string	—
`user.onedrive`	body	string	—
`user.originalRefreshToken`	body	string	—
`user.originalToken`	body	string	—
`user.oura`	body	string	—
`user.owner`	body	string	—	Identity / tenancy.
`user.passwordHash`	body	string	—	Credential material.
`user.passwordSalt`	body	string	—
`user.passwordType`	body	string	—
`user.patreon`	body	string	—
`user.paypal`	body	string	—
`user.permanentAvatar`	body	string	—
`user.phone`	body	string	—
`user.preHash`	body	string	—
`user.preferredMfaType`	body	string	—
`user.properties`	body	object	—
`user.properties.*`	body	string	—
`user.qq`	body	string	—
`user.ranking`	body	integer (int64)	—
`user.realName`	body	string	—
`user.recoveryCodes`	body	string[]	—
`user.region`	body	string	—
`user.registerSource`	body	string	—
`user.registerType`	body	string	—
`user.salesforce`	body	string	—
`user.score`	body	integer (int64)	—
`user.shopify`	body	string	—
`user.signinWrongTimes`	body	integer (int64)	—
`user.signupApplication`	body	string	—
`user.slack`	body	string	—
`user.soundcloud`	body	string	—
`user.spotify`	body	string	—
`user.steam`	body	string	—
`user.strava`	body	string	—
`user.stripe`	body	string	—
`user.tag`	body	string	—
`user.telegram`	body	string	—
`user.tiktok`	body	string	—
`user.title`	body	string	—
`user.totpSecret`	body	string	—
`user.tumblr`	body	string	—
`user.twitch`	body	string	—
`user.twitter`	body	string	—
`user.type`	body	string	—
`user.typetalk`	body	string	—
`user.uber`	body	string	—
`user.updatedAt`	body	string (date-time)	—
`user.updatedTime`	body	string	—
`user.verificationCode`	body	string	—
`user.vk`	body	string	—
`user.webauthnCredentials`	body	any[]	—	Multi-factor authentication.
`user.wechat`	body	string	—
`user.wecom`	body	string	—
`user.weibo`	body	string	—
`user.wepay`	body	string	—
`user.xero`	body	string	—
`user.yahoo`	body	string	—
`user.yammer`	body	string	—
`user.yandex`	body	string	—
`user.zoom`	body	string	—

Response

Status	Body	Meaning
`200`	iam.User	ok
`202`	Approval	held for approval
`default`	problem-details	refused

200 body — 217 fields.

Field	In	Type	Always	Description
`accessKey`	body	string	—	API credentials.
`accessSecret`	body	string	—
`accessSecretHash`	body	string	—
`accessToken`	body	string	—
`address`	body	string[]	—
`addresses`	body	iam.Address[]	—
`addresses[].city`	body	string	—
`addresses[].line1`	body	string	—
`addresses[].line2`	body	string	—
`addresses[].region`	body	string	—
`addresses[].state`	body	string	—
`addresses[].tag`	body	string	—
`addresses[].zipCode`	body	string	—
`adfs`	body	string	—
`affiliation`	body	string	—
`alipay`	body	string	—
`amazon`	body	string	—
`apple`	body	string	—
`applicationScopes`	body	iam.ConsentRecord[]	—
`applicationScopes[].application`	body	string	—
`applicationScopes[].grantedScopes`	body	string[]	—
`auth0`	body	string	—
`avatar`	body	string	—
`avatarType`	body	string	—
`azuread`	body	string	—
`azureadb2c`	body	string	—
`baidu`	body	string	—
`balance`	body	number (double)	—	Balance mirrors v1 for lossless migration but is authoritative in Commerce (billing.hanzo.ai), not here — do not write it from IAM.
`balanceCredit`	body	number (double)	—
`balanceCurrency`	body	string	—
`battlenet`	body	string	—
`bilibili`	body	string	—
`bio`	body	string	—
`birthday`	body	string	—
`bitbucket`	body	string	—
`box`	body	string	—
`cart`	body	iam.CartItem[]	—
`cart[].displayName`	body	string	—
`cart[].name`	body	string	—
`cart[].owner`	body	string	—
`cart[].price`	body	number (double)	—
`cart[].quantity`	body	integer (int64)	—
`cloudfoundry`	body	string	—
`countryCode`	body	string	—
`createdAt`	body	string (date-time)	—
`createdIp`	body	string	—	Sign-in provenance.
`createdTime`	body	string	—
`currency`	body	string	—
`custom`	body	string	—
`custom2`	body	string	—
`custom3`	body	string	—
`custom4`	body	string	—
`custom5`	body	string	—
`custom6`	body	string	—
`custom7`	body	string	—
`custom8`	body	string	—
`custom9`	body	string	—
`custom10`	body	string	—
`dailymotion`	body	string	—
`deezer`	body	string	—
`deleted`	body	boolean	—
`deletedTime`	body	string	—
`digitalocean`	body	string	—
`dingtalk`	body	string	—
`discord`	body	string	—
`displayName`	body	string	—	Profile.
`douyin`	body	string	—
`dropbox`	body	string	—
`education`	body	string	—
`email`	body	string	—
`emailVerified`	body	boolean	—
`eveonline`	body	string	—
`externalId`	body	string	—
`faceIds`	body	iam.FaceId[]	—
`faceIds[].faceIdData`	body	number (double)[]	—
`faceIds[].imageUrl`	body	string	—
`faceIds[].name`	body	string	—
`facebook`	body	string	—
`firstName`	body	string	—
`fitbit`	body	string	—
`gender`	body	string	—
`gitea`	body	string	—
`gitee`	body	string	—
`github`	body	string	—	Linked federated-identity subjects, one column per connector (v1 parity).
`gitlab`	body	string	—
`google`	body	string	—
`hash`	body	string	—
`heroku`	body	string	—
`homepage`	body	string	—
`iam`	body	string	—
`id`	body	string	—	Id is the user's STABLE OPAQUE identifier — the value the OIDC `sub` claim carries.
`idCard`	body	string	—
`idCardType`	body	string	—
`influxcloud`	body	string	—
`infoflow`	body	string	—
`instagram`	body	string	—
`intercom`	body	string	—
`invitation`	body	string	—
`invitationCode`	body	string	—
`ipWhitelist`	body	string	—
`isAdmin`	body	boolean	—
`isDefaultAvatar`	body	boolean	—	State flags.
`isDeleted`	body	boolean	—
`isForbidden`	body	boolean	—
`isOnline`	body	boolean	—
`isVerified`	body	boolean	—
`kakao`	body	string	—
`karma`	body	integer (int64)	—
`kwai`	body	string	—
`language`	body	string	—
`lark`	body	string	—
`lastChangePasswordTime`	body	string	—
`lastName`	body	string	—
`lastSigninIp`	body	string	—
`lastSigninTime`	body	string	—
`lastSigninWrongTime`	body	string	—
`lastfm`	body	string	—
`ldap`	body	string	—
`line`	body	string	—
`linkedin`	body	string	—
`location`	body	string	—
`mailru`	body	string	—
`managedAccounts`	body	iam.ManagedAccount[]	—
`managedAccounts[].application`	body	string	—
`managedAccounts[].signinUrl`	body	string	—
`managedAccounts[].username`	body	string	—
`meetup`	body	string	—
`mfaAccounts`	body	iam.MfaAccount[]	—
`mfaAccounts[].accountName`	body	string	—
`mfaAccounts[].issuer`	body	string	—
`mfaAccounts[].origin`	body	string	—
`mfaEmailEnabled`	body	boolean	—
`mfaItems`	body	iam.MfaItem[]	—
`mfaItems[].name`	body	string	—
`mfaItems[].rule`	body	string	—
`mfaPhoneEnabled`	body	boolean	—
`mfaPushEnabled`	body	boolean	—
`mfaPushProvider`	body	string	—
`mfaPushReceiver`	body	string	—
`mfaRadiusEnabled`	body	boolean	—
`mfaRadiusProvider`	body	string	—
`mfaRadiusUsername`	body	string	—
`mfaRememberDeadline`	body	string	—
`mfaRememberDigest`	body	string	—	MfaRememberDigest is the digest of the token held by the ONE browser the deadline above applies to.
`microsoftonline`	body	string	—
`multiFactorAuths`	body	iam.MfaProps[]	—
`multiFactorAuths[].countryCode`	body	string	—
`multiFactorAuths[].enabled`	body	boolean	—
`multiFactorAuths[].isPreferred`	body	boolean	—
`multiFactorAuths[].mfaRememberInHours`	body	integer (int64)	—
`multiFactorAuths[].mfaType`	body	string	—
`multiFactorAuths[].url`	body	string	—
`name`	body	string	—
`nameKey`	body	string	—	NameKey is Fold(Name), derived on every save (BeforeCreate, BeforeUpdate) and on every open for a row saved without it (store.Prepare): the indexed key a case-insensitive username lookup reads (store.GetUserByName).
`naver`	body	string	—
`needUpdatePassword`	body	boolean	—
`nextcloud`	body	string	—
`okta`	body	string	—
`onedrive`	body	string	—
`originalRefreshToken`	body	string	—
`originalToken`	body	string	—
`oura`	body	string	—
`owner`	body	string	—	Identity / tenancy.
`passwordHash`	body	string	—	Credential material.
`passwordSalt`	body	string	—
`passwordType`	body	string	—
`patreon`	body	string	—
`paypal`	body	string	—
`permanentAvatar`	body	string	—
`phone`	body	string	—
`preHash`	body	string	—
`preferredMfaType`	body	string	—
`properties`	body	object	—
`properties.*`	body	string	—
`qq`	body	string	—
`ranking`	body	integer (int64)	—
`realName`	body	string	—
`recoveryCodes`	body	string[]	—
`region`	body	string	—
`registerSource`	body	string	—
`registerType`	body	string	—
`salesforce`	body	string	—
`score`	body	integer (int64)	—
`shopify`	body	string	—
`signinWrongTimes`	body	integer (int64)	—
`signupApplication`	body	string	—
`slack`	body	string	—
`soundcloud`	body	string	—
`spotify`	body	string	—
`steam`	body	string	—
`strava`	body	string	—
`stripe`	body	string	—
`tag`	body	string	—
`telegram`	body	string	—
`tiktok`	body	string	—
`title`	body	string	—
`totpSecret`	body	string	—
`tumblr`	body	string	—
`twitch`	body	string	—
`twitter`	body	string	—
`type`	body	string	—
`typetalk`	body	string	—
`uber`	body	string	—
`updatedAt`	body	string (date-time)	—
`updatedTime`	body	string	—
`verificationCode`	body	string	—
`vk`	body	string	—
`webauthnCredentials`	body	any[]	—	Multi-factor authentication.
`wechat`	body	string	—
`wecom`	body	string	—
`weibo`	body	string	—
`wepay`	body	string	—
`xero`	body	string	—
`yahoo`	body	string	—
`yammer`	body	string	—
`yandex`	body	string	—
`zoom`	body	string	—

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo iam users create

.ts

.py

.go

.rs

.java

import { Configuration, IamApi } from 'hanzoai';

const api = new IamApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postIamUsers({ password: "<password>", user: {"accessKey":"<accessKey>","accessSecret":"<accessSecret>","accessSecretHash":"<accessSecretHash>","accessToken":"<accessToken>"} });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import IamApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = IamApi(client).post_iam_users(password="<password>", user={"accessKey":"<accessKey>","accessSecret":"<accessSecret>","accessSecretHash":"<accessSecretHash>","accessToken":"<accessToken>"})

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.IamAPI.PostIamUsers(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, iam_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = iam_api::post_iam_users(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.IamApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new IamApi(client).postIamUsers();

curl -X POST https://api.hanzo.ai/v1/iam/users \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "password": "<password>",
       "user": {
         "accessKey": "<accessKey>",
         "accessSecret": "<accessSecret>",
         "accessSecretHash": "<accessSecretHash>",
         "accessToken": "<accessToken>"
       }
     }'

MCP reaches iam through the iam tool, which names its 44 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_iam_applications"
         }
       }
     }'

IAM API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousCreate keys — POST /v1/iam/users/{owner}/{name}/keys NextCreate verification codes