> Tychron Atlas API & Provisioning Reference — chapter 13 of 35 as Markdown. Web version: https://docs.tychron.com/api-reference/users/
> Source: https://docs.tychron.com/api-reference/ · Updated 2026-08-12 · Generated from the Atlas OpenAPI spec (https://api.atlas.tychron.online/api/v1/openapi is the live contract; this file is a dated snapshot of it).
> Source revision: atlas_api_reference_2026-08-12.md · sha256 482ebd3b014af053 · sanitize gate v1 clean · reconciled with OpenAPI 2026.8.25-p01 (spec sha256 cc049ef38c71cd6e) on 2026-09-05 · content last modified 2026-09-09 · newer definition under review since 2026-09-09 (not yet reconciled)
> Scope: the Atlas platform API only. The SMS, MMS, CNAM, LRN and MCL services are separate APIs with their own specifications: https://docs.tychron.com/openapi/
> Machine index: https://docs.tychron.com/llms.txt

# Users

## Schema

A user is any agent that can interact with impersonated or portal APIs


__Type__ Object

| Name          | Type                     | Description                     |
| ------------- | ------------------------ | ------------------------------- |
| `address`     | `address`                | [Desc. `address`](https://docs.tychron.com/api-reference/users/#desc-174)    |
| `email`       | String(format:email)     | [Desc. `email`](https://docs.tychron.com/api-reference/users/#desc-175)      |
| `first_name`  | String                   | [Desc. `first_name`](https://docs.tychron.com/api-reference/users/#desc-176) |
| `id`          | String(format:uuid)      | [Desc. `id`](https://docs.tychron.com/api-reference/users/#desc-177)         |
| `inserted_at` | String(format:date-time) | An ISO8601 formatted timestamp  |
| `last_name`   | String                   | [Desc. `last_name`](https://docs.tychron.com/api-reference/users/#desc-178)  |
| `title`       | String                   | [Desc. `title`](https://docs.tychron.com/api-reference/users/#desc-179)      |
| `updated_at`  | String(format:date-time) | An ISO8601 formatted timestamp  |

#### Desc. `address` {#desc-174}

User Address details, may differ from top-level details

#### Desc. `email` {#desc-175}

User's email

#### Desc. `first_name` {#desc-176}

User's first name

#### Desc. `id` {#desc-177}

A Universally unique identifier, which identifies the resource

#### Desc. `last_name` {#desc-178}

User's last name

#### Desc. `title` {#desc-179}

User's job title, or position

__address__

| Name            | Type   | Description |
| --------------- | ------ | ----------- |
| `address1`      | String |             |
| `address2`      | String |             |
| `business_name` | String |             |
| `city`          | String |             |
| `country`       | String |             |
| `email`         | String |             |
| `fax_number`    | String |             |
| `first_name`    | String |             |
| `house_number`  | String |             |
| `last_name`     | String |             |
| `notes`         | String |             |
| `phone_number`  | String |             |
| `state`         | String |             |
| `zip_code`      | String |             |



__Example__

```json
{
  "address": {
    "address1": "string",
    "address2": "string",
    "business_name": "string",
    "city": "string",
    "country": "string",
    "email": "string",
    "fax_number": "string",
    "first_name": "string",
    "house_number": "string",
    "last_name": "string",
    "notes": "string",
    "phone_number": "string",
    "state": "string",
    "zip_code": "string"
  },
  "email": "john.doe@example.com",
  "first_name": "John",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "last_name": "Doe",
  "title": "Operator",
  "updated_at": "2021-08-13T04:08:44.762841Z"
}
```


## Summary

Users are agents or actual human beings who are capable of utilizing the portal or API (via an Impersonated API Key).

Users are assigned a `role` which affect their permissions and access levels.

## API

### Create User

__Data__

| Name                    | Type                 | Description                                |
| ----------------------- | -------------------- | ------------------------------------------ |
| `address`               | `address`            | [Desc. `address`](https://docs.tychron.com/api-reference/users/#desc-180)               |
| `email`                 | String(format:email) | [Desc. `email`](https://docs.tychron.com/api-reference/users/#desc-181)                 |
| `first_name`            | String               | [Desc. `first_name`](https://docs.tychron.com/api-reference/users/#desc-182)            |
| `last_name`             | String               | [Desc. `last_name`](https://docs.tychron.com/api-reference/users/#desc-183)             |
| `password`              | String               | [Desc. `password`](https://docs.tychron.com/api-reference/users/#desc-184)              |
| `password_confirmation` | String               | [Desc. `password_confirmation`](https://docs.tychron.com/api-reference/users/#desc-185) |
| `title`                 | String               | [Desc. `title`](https://docs.tychron.com/api-reference/users/#desc-186)                 |

#### Desc. `address` {#desc-180}

User Address details, may differ from top-level details

#### Desc. `email` {#desc-181}

User's email

#### Desc. `first_name` {#desc-182}

User's first name

#### Desc. `last_name` {#desc-183}

User's last name

#### Desc. `password` {#desc-184}

User's login password

#### Desc. `password_confirmation` {#desc-185}

User's login password (for confirmation)

#### Desc. `title` {#desc-186}

User's job title, or position

__address__

| Name            | Type   | Description |
| --------------- | ------ | ----------- |
| `address1`      | String |             |
| `address2`      | String |             |
| `business_name` | String |             |
| `city`          | String |             |
| `country`       | String |             |
| `email`         | String |             |
| `fax_number`    | String |             |
| `first_name`    | String |             |
| `house_number`  | String |             |
| `last_name`     | String |             |
| `notes`         | String |             |
| `phone_number`  | String |             |
| `state`         | String |             |
| `zip_code`      | String |             |



```http
POST /api/v1/users HTTP/1.1
```

Create a new User, they will be automatically assigned to the same role as current user.


#### Request application/json

```http
POST /api/v1/users HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 632
```

```json
{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "password": "string",
    "password_confirmation": "string",
    "title": "Operator"
  },
  "type": "user"
}
```

#### Response 201

##### application/json

```http
HTTP/1.1 201
Content-Type: application/json
Content-Length: 716
```

```json
{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "john.doe@example.com",
    "first_name": "John",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "last_name": "Doe",
    "title": "Operator",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "user"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 422

##### application/json

```http
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Update User

__Data__

| Name         | Type                 | Description                     |
| ------------ | -------------------- | ------------------------------- |
| `address`    | `address`            | [Desc. `address`](https://docs.tychron.com/api-reference/users/#desc-187)    |
| `email`      | String(format:email) | [Desc. `email`](https://docs.tychron.com/api-reference/users/#desc-188)      |
| `first_name` | String               | [Desc. `first_name`](https://docs.tychron.com/api-reference/users/#desc-189) |
| `last_name`  | String               | [Desc. `last_name`](https://docs.tychron.com/api-reference/users/#desc-190)  |
| `title`      | String               | [Desc. `title`](https://docs.tychron.com/api-reference/users/#desc-191)      |

#### Desc. `address` {#desc-187}

User Address details, may differ from top-level details

#### Desc. `email` {#desc-188}

User's email

#### Desc. `first_name` {#desc-189}

User's first name

#### Desc. `last_name` {#desc-190}

User's last name

#### Desc. `title` {#desc-191}

User's job title, or position

__address__

| Name            | Type   | Description |
| --------------- | ------ | ----------- |
| `address1`      | String |             |
| `address2`      | String |             |
| `business_name` | String |             |
| `city`          | String |             |
| `country`       | String |             |
| `email`         | String |             |
| `fax_number`    | String |             |
| `first_name`    | String |             |
| `house_number`  | String |             |
| `last_name`     | String |             |
| `notes`         | String |             |
| `phone_number`  | String |             |
| `state`         | String |             |
| `zip_code`      | String |             |



```http
PATCH /api/v1/users/{id} HTTP/1.1
```

Update an existing User.


__Path Parameters__

| Name | Type                 | Description |
| ---- | -------------------- | ----------- |
| id   | String(format:uuid)! | User ID     |

#### Request application/json

```http
PATCH /api/v1/users/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 567
```

```json
{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "title": "Operator"
  },
  "type": "user"
}
```

#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 716
```

```json
{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "john.doe@example.com",
    "first_name": "John",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "last_name": "Doe",
    "title": "Operator",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "user"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```
#### Response 422

##### application/json

```http
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### Delete User

```http
DELETE /api/v1/users/{id} HTTP/1.1
```

Delete an existing User by ID.


__Path Parameters__

| Name | Type                 | Description |
| ---- | -------------------- | ----------- |
| id   | String(format:uuid)! | User ID     |

#### Request

```http
DELETE /api/v1/users/{id} HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 716
```

```json
{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "john.doe@example.com",
    "first_name": "John",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "last_name": "Doe",
    "title": "Operator",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "user"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```
#### Response 422

##### application/json

```http
HTTP/1.1 422
Content-Type: application/json
Content-Length: 241
```

```json
{
  "errors": [
    {
      "code": "invalid_parameter",
      "detail": "The specified resource could not be found",
      "source": {
        "pointer": "/data/type"
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```


### List Users

```http
GET /api/v1/users HTTP/1.1
```

Retrieve a list of users assigned to the parent account


__Query Parameters__

| Name   | Type    | Description                     |
| ------ | ------- | ------------------------------- |
| first  | Integer | [Query Desc. first](https://docs.tychron.com/api-reference/users/#desc-192)  |
| last   | Integer | [Query Desc. last](https://docs.tychron.com/api-reference/users/#desc-193)   |
| after  | String  | [Query Desc. after](https://docs.tychron.com/api-reference/users/#desc-194)  |
| before | String  | [Query Desc. before](https://docs.tychron.com/api-reference/users/#desc-195) |

#### Query Desc. first {#desc-192}

The number of items to return starting from the 'after' cursor

#### Query Desc. last {#desc-193}

The number of items to return behind the 'before' cursor

#### Query Desc. after {#desc-194}

The cursor representing the starting point of a 'first' based paging

#### Query Desc. before {#desc-195}

The cursor representing the starting point of a 'last' based paging

#### Request

```http
GET /api/v1/users HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 989
```

```json
{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "address": {
          "address1": "string",
          "address2": "string",
          "business_name": "string",
          "city": "string",
          "country": "string",
          "email": "string",
          "fax_number": "string",
          "first_name": "string",
          "house_number": "string",
          "last_name": "string",
          "notes": "string",
          "phone_number": "string",
          "state": "string",
          "zip_code": "string"
        },
        "email": "john.doe@example.com",
        "first_name": "John",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "last_name": "Doe",
        "title": "Operator",
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "user"
    }
  ]
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```


### Get User

```http
GET /api/v1/users/{id} HTTP/1.1
```

Lookup a user by ID


__Path Parameters__

| Name | Type                 | Description |
| ---- | -------------------- | ----------- |
| id   | String(format:uuid)! | User ID     |

#### Request

```http
GET /api/v1/users/{id} HTTP/1.1
Accept: application/json
```
#### Response 200

##### application/json

```http
HTTP/1.1 200
Content-Type: application/json
Content-Length: 716
```

```json
{
  "data": {
    "address": {
      "address1": "string",
      "address2": "string",
      "business_name": "string",
      "city": "string",
      "country": "string",
      "email": "string",
      "fax_number": "string",
      "first_name": "string",
      "house_number": "string",
      "last_name": "string",
      "notes": "string",
      "phone_number": "string",
      "state": "string",
      "zip_code": "string"
    },
    "email": "john.doe@example.com",
    "first_name": "John",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "last_name": "Doe",
    "title": "Operator",
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "user"
}
```
#### Response 403

##### application/json

```http
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312
```

```json
{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}
```
#### Response 404

##### application/json

```http
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314
```

```json
{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}
```

---

Previous chapter: https://docs.tychron.com/api-reference/roles.md  
Next chapter: https://docs.tychron.com/api-reference/api-keys.md  
Complete reference in one file: https://docs.tychron.com/llms-full.txt