---
title: "POST /users"
method: POST
path: "/users"
tags: ["Users"]
---

# POST /users

`POST /users`

## Request

- Base URL: `https://api.axiom.co/v2`
- URL: `https://api.axiom.co/v2/users`
- Auth: OAuth 2
  - Authorization code: `https://accounts.google.com/o/oauth2/v2/auth`
  - Token URL: `https://www.googleapis.com/oauth2/v4/token` scopes: `users|create`
- TypeScript: <https://skmtc.dev/axiom/apis/axiom-public-api/docs/users/post.ts> (a function with typed inputs; its response is checked against the schema)

Adds a user to the organization with the given role and sends them an invite email. If the email address already belongs to an Axiom account, Axiom keeps its existing name. API tokens can't assign the `owner` role.

## Request body

- CreateUserRequest: Object representing a new user creation request
  - `email` string, required: Email address of the new user
  - `name` string, required: Full name of the new user
  - `role` string, required: Role to assign to the new user

## Response `200`

Added user.

- User: Represents a user in the system
  - `email` string, required: User's email address
  - `id` string, required: Unique identifier for the user
  - `name` string, required: User's full name
  - `role` UserDetailsRole, required: Detailed information about a user's role
    - `id` string, required: Unique identifier for the role
    - `name` string, required: Human-readable name of the role

## Other responses

- `400`: Invalid email address, the user is already a member, or the organization has reached its user limit.
- `403`: Insufficient permissions, or the caller isn't allowed to assign the `owner` role.
- `404`: Role not found.

## Changes

- **2026-10-16** (v2) `fbc1b8430feb`: 3 info
  - added the non-success response with the status `400`
  - added the non-success response with the status `403`
  - added the non-success response with the status `404`

[Operation history](https://skmtc.dev/axiom/apis/axiom-public-api/changes/users/post.md)

---

[API](https://skmtc.dev/axiom/apis/axiom-public-api.md) - [All operations](https://skmtc.dev/axiom/apis/axiom-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/axiom/apis/axiom-public-api/revisions/7e39a295e3ba?raw)