Create identities

POST /v1/network/identities

Puts the caller on the org's overlay as its own IAM subject.

The identity is the one whose externalId is the caller's sub, admitted by the controller's "iam" auth policy: the caller logs in to the fabric with its own IAM access token, and nothing is enrolled. It is named by the subject unless a name is given, and carries the org's "org-<org>" role attribute plus any supplied roles — each scoped to the org, and a "<service>-host" role refused unless the org has published that service. Roles are a steward's to take: a plain member joins with the org role alone, and asking for more is 403 before the controller is written.

An API key is refused 403: the fabric admits an IAM access token, a person's or an application's, and a key has none to log in with.

IDEMPOTENT: a caller who already has an identity gets the same one back, with any of these roles it lacked added — which is how one person's identity comes to serve every org they act in.

A write, so it does not degrade: an unconfigured deployment answers 503.

Request

2 fields, body application/json (required).

Response

201 body — 4 fields.

Failure carries the platform error shape — see Errors.

Examples

hanzo network identities create

import { Configuration, NetworkApi } from 'hanzoai';

const api = new NetworkApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postNetworkIdentities({ name: "<name>", roles: ["<roles>"] });

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

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = NetworkApi(client).post_network_identities(name="<name>", roles=["<roles>"])

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

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

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

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

let result = network_api::post_network_identities(&cfg, Default::default()).await?;

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

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

var result = new NetworkApi(client).postNetworkIdentities();

curl -X POST https://api.hanzo.ai/v1/network/identities \
  -H "Authorization: Bearer $HANZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "<name>",
       "roles": [
         "<roles>"
       ]
     }'

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_networks"
         }
       }
     }'

Network API · All Hanzo APIs · Interactive reference