Create User Account ​

Create a new user account for one of your customers.

Request ​

http
POST /v1/admin/users
Authorization: Bearer {admin_key}
Content-Type: application/json

Body Parameters ​

ParameterTypeRequiredDescription
namestringYesUser or company name (max 255 chars)
external_idstringNoYour customer ID for reference
emailstringNoContact email address
metadataobjectNoCustom key-value data
billing_planstringNoYour billing plan identifier

Example Request ​

bash
curl -X POST "https://api.insight.iagon.com/v1/admin/users" \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corporation", "external_id": "cust_abc123", "email": "api@acme.com", "metadata": {"tier": "enterprise", "signup_source": "referral"}, "billing_plan": "pro"}'

Response ​

Success (201 Created) ​

json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "admin_key_id": "660e8400-e29b-41d4-a716-446655440001",
    "admin_entity_name": "YourCompany",
    "external_id": "cust_abc123",
    "name": "Acme Corporation",
    "email": "api@acme.com",
    "metadata": {
      "tier": "enterprise",
      "signup_source": "referral"
    },
    "created_at": "2026-01-26T12:00:00Z",
    "updated_at": null,
    "status": "active",
    "billing_plan": "pro"
  },
  "message": "User account created successfully"
}

Error Responses ​

400 Bad Request - Missing or invalid name:

json
{
  "success": false,
  "error": "Name is required and must be a non-empty string"
}

400 Bad Request - Bootstrap key used:

json
{
  "success": false,
  "error": "Bootstrap key cannot manage users. Create an admin key first."
}

403 Forbidden - Missing permission:

json
{
  "success": false,
  "error": "Permission denied: manage_users required"
}

Notes ​

  • The user is automatically scoped to your admin key
  • Users start with status: "active" by default
  • Use external_id to link to your own customer database
  • The metadata field can store any JSON object for custom data