Replace address

Adds an email address or a phone number to the calling person's own account, so they can sign in with it — by a code sent there, or to recover a password.

PUT /v1/iam/address

IAM → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/iam/address`
Method	`PUT`
Operation	`put_iam_address`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Adds an email address or a phone number to the calling person's own account, so they can sign in with it — by a code sent there, or to recover a password.

First ask POST /v1/iam/verification-codes to send a code to the new address, with the applicationId of the application you sign in at, then send that application's clientId, the address and the code here. Only the caller's own account is written; the request names nobody.

It adds and never replaces: an account that already has an email keeps it, and asking again with the same address answers ok. An address another account at that application already signs in with is refused with the same words a wrong code gets.

Request

9 fields, body application/json (required).

Field	In	Type	Required	Description
`Cookie`	header	string	—
`Authorization`	header	string	—
`Sec-Fetch-Site`	header	string	—
`Origin`	header	string	—
`Host`	header	string	—
`Content-Type`	header	string	—
`address`	body	string	—	Address is the email address or phone number being added.
`clientId`	body	string	—	ClientId is the application the address will sign in at — the one whose applicationId the code was sent under.
`code`	body	string	—	Code is the one-time code sent to Address.

Response

Status	Body	Meaning
`200`	iam.Answer	ok
`400`	iam.Answer	bad request
`403`	iam.Answer	forbidden
`409`	iam.Answer	conflict
`default`	problem-details	refused

200 body — 8 fields.

Field	In	Type	Always	Description
`code`	body	string	—	Code is a STABLE machine-readable reason, where the human `msg` is deliberately generic.
`data`	body	any	—
`data2`	body	any	—
`data3`	body	any	—
`msg`	body	string	—
`name`	body	string	—
`status`	body	string	—
`sub`	body	string	—

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo iam address

.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.putIamAddress({ address: "<address>", clientId: "<clientId>" });

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).put_iam_address(address="<address>", client_id="<clientId>")

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

resp, _, err := client.IamAPI.PutIamAddress(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::put_iam_address(&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).putIamAddress();

The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →

curl -X PUT https://api.hanzo.ai/v1/iam/address \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "address": "<address>",
       "clientId": "<clientId>"
     }'

MCP reaches iam through the iam tool, which names its 46 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?

Broken link or missing step? Drop it in #docs on Discord or open a PR.

PreviousReplace accounts NextReplace applications