Create User

Create a new user identity with email, password, and profile data via the admin API.

Endpoint

POST /v1/identities

Base URL: https://api-id.avnology.net

Authentication: API Key or OAuth token with admin:users:write scope

Request

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <api_key>` or `Bearer <access_token>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	Prevents duplicate creation on retries

Body

Field	Type	Required	Description
`identity.email`	string	Yes	User's email address
`identity.username`	string	No	Unique username (3--64 chars, alphanumeric + `-_`)
`identity.first_name`	string	No	First name
`identity.last_name`	string	No	Last name
`identity.display_name`	string	No	Display name
`identity.phone`	string	No	Phone in E.164 format (e.g., `+14155551234`)
`identity.organization_id`	string	No	Assign to an organization
`identity.locale`	string	No	BCP 47 locale (e.g., `en-US`)
`identity.timezone`	string	No	IANA timezone (e.g., `America/New_York`)
`identity.traits`	object	No	Custom profile attributes
`identity.admin_metadata`	object	No	Admin-only metadata (not visible to user)
`initial_password`	string	No	Initial password (min 8 chars, hashed with Argon2id)
`validate_only`	boolean	No	If `true`, validate without creating

Example Request

curl -X POST https://api-id.avnology.net/v1/identities \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "identity": {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Smith",
      "phone": "+14155551234",
      "organization_id": "org_7a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "traits": { "department": "Engineering" }
    },
    "initial_password": "SecureP@ssw0rd!"
  }'

Response

Success (201 Created)

{
  "id": "usr_4f18acec-2712-4be7-a9af-b063b4f6deba",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Smith",
  "phone": "+14155551234",
  "email_verified": false,
  "phone_verified": false,
  "state": "active",

Errors

Status	Code	Description
400	`AVNOLOGY_AUTH_902`	Validation failed (invalid email, phone format, etc.)
400	`AVNOLOGY_AUTH_011`	Password does not meet policy requirements
400	`AVNOLOGY_AUTH_010`	Password found in breach database
409	`AVNOLOGY_AUTH_014`	Email already exists
403	`AVNOLOGY_AUTH_100`	Insufficient permissions
429	`AVNOLOGY_AUTH_021`	Rate limit exceeded

Error Example

{
  "error": {
    "code": "AVNOLOGY_AUTH_014",
    "message": "A user with this email already exists",
    "status": 409,
    "details": { "field": "email", "value": "[email protected]" }
  }
}

Code Examples

JavaScript (fetch)

async function createUser(apiKey, userData) {
  const response = await fetch('https://api-id.avnology.net/v1/identities', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type':

Python (httpx)

import httpx

def create_user(api_key: str, email: str, first_name: str, last_name: str, password: str, org_id: str = "") -> dict:
    return

Go (net/http)

func createUser(ctx context.Context, apiKey string, user *CreateUserRequest) (*Identity, error) {
	jsonBody, _

Get User -- retrieve the created user
Update User -- modify user fields
List Users -- paginated user listing
SDK: client.admin.createUser({ email, password, name }) (TypeScript)

On this page