# User Management API

![](/files/-MLEz8W_-gZI3YVA4vlf)

## Get Users

<mark style="color:blue;">`GET`</mark> `/users/`

This endpoint allows you to get a list of users.

#### Headers

| Name           | Type   | Description                       |
| -------------- | ------ | --------------------------------- |
| Authentication | string | Authentication token from Cognito |

{% tabs %}
{% tab title="200 Users successfully retrieved." %}

```
[
  {
    "Attributes": [
      {
        "Name": "sub",
        "Value": "<Cognito Username>"
      },
      {
        "Name": "email_verified",
        "Value": "true"
      },
      {
        "Name": "email",
        "Value": "<User email>"
      }
    ],
    "Enabled": true,
    "UserCreateDate": "Fri, 09 Oct 2020 17:39:20 GMT",
    "UserLastModifiedDate": "Fri, 09 Oct 2020 17:39:20 GMT",
    "UserStatus": "CONFIRMED",
    "Username": "<Cognito Username>"
  },
  <Other users>
]
```

{% endtab %}

{% tab title="403 You don't have a valid token from Cognito." %}

```
You don't have the permission to access the requested resource. It is either read-protected or not readable by the server.
```

{% endtab %}
{% endtabs %}

## Get User

<mark style="color:blue;">`GET`</mark> `/users/:id`

This endpoint allows you to get a user's details.

#### Path Parameters

| Name | Type   | Description     |
| ---- | ------ | --------------- |
| id   | string | User Cognito ID |

#### Headers

| Name          | Type   | Description                       |
| ------------- | ------ | --------------------------------- |
| Authenticaion | string | Authentication token from Cognito |

{% tabs %}
{% tab title="200 User successfully retrieved." %}

```
{
  "Enabled": true,
  "ResponseMetadata": {
    "HTTPHeaders": {
      "connection": "keep-alive",
      "content-length": "344",
      "content-type": "application/x-amz-json-1.1",
      "date": "Mon, 12 Oct 2020 16:00:26 GMT",
      "x-amzn-requestid": "b88e891b-a0ec-4e21-bc96-d477eaf13b4e"
    },
    "HTTPStatusCode": 200,
    "RequestId": "b88e891b-a0ec-4e21-bc96-d477eaf13b4e",
    "RetryAttempts": 0
  },
  "UserAttributes": [
    {
      "Name": "sub",
      "Value": "<Cognito Username>"
    },
    {
      "Name": "email_verified",
      "Value": "true"
    },
    {
      "Name": "email",
      "Value": "<User email>"
    }
  ],
  "UserCreateDate": "Wed, 23 Sep 2020 17:37:00 GMT",
  "UserLastModifiedDate": "Wed, 23 Sep 2020 22:01:51 GMT",
  "UserStatus": "CONFIRMED",
  "Username": "<Cognito Username>",
  "x-hasura-allowed-roles": [
    "user", <Other user roles>
  ],
  "x-hasura-default-role": "user",
  "x-hasura-user-id": "<Cognito Username>"
}
```

{% endtab %}

{% tab title="403 You don't have a valid token from Cognito." %}

```
You don't have the permission to access the requested resource. It is either read-protected or not readable by the server.
```

{% endtab %}
{% endtabs %}

## Create User

<mark style="color:green;">`POST`</mark> `/users/`

This endpoint allows you to create a new user. \*Requires admin role

#### Headers

| Name           | Type   | Description                       |
| -------------- | ------ | --------------------------------- |
| Authentication | string | Authentication token from Cognito |

#### Request Body

| Name           | Type    | Description                                                                                                                                                                 |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| date\_added    | string  | An iso date to be provided if you want to override the date the user was created. ISO format: "YYYY-MM-DD HH-MM-SS"                                                         |
| email          | string  | The users email address. Min. length: 8, max. length: 128                                                                                                                   |
| first\_name    | string  | The first name of the user. Only alphanumeric characters, white spaces and hyphens. Min. Length: 1, Max Length: 128                                                         |
| last\_name     | string  | The last name of the user. Only alphanumeric characters, white spaces and hyphens. Min. Length: 1, Max Length: 128                                                          |
| is\_coa\_staff | boolean | True if the user is part of the City of Austin, False otherwise. If this field is not provided, this is automatically set to True if the email ends with "@austintexas.gov" |
| status\_id     | integer | The status of the user, 0 for inactive, 1 for active.                                                                                                                       |
| title          | string  | The job position title of the user.                                                                                                                                         |
| workgroup      | string  | The workgroup name. Not empty, min length: 3, max length: 128. Allowed characters: a-z, A-Z, 0-9, and any of these special characters: \_-!@%^\~?.:&()\[]$                  |
| workgroup\_id  | integer | The workgroup\_id in the moped\_workgroup table in the database.                                                                                                            |
| password       | string  | The new user's password. Allowed characters: a-z, A-Z, 0-9, and any of these special characters: \_-!@%^*\~?.:&*()\[]$                                                      |
| roles          | array   | Array of strings, must be at least one value. It must be at least one of these values: "moped-admin", "moped-editor" or "moped-viewer"                                      |

{% tabs %}
{% tab title="200 User created successfully." %}

```
{
  "ResponseMetadata": {
    "HTTPHeaders": {
      "connection": "keep-alive",
      "content-length": "359",
      "content-type": "application/x-amz-json-1.1",
      "date": "Fri, 09 Oct 2020 17:39:20 GMT",
      "x-amzn-requestid": "b6705165-b888-432e-a31b-8af46302fe52"
    },
    "HTTPStatusCode": 200,
    "RequestId": "b6705165-b888-432e-a31b-8af46302fe52",
    "RetryAttempts": 0
  },
  "User": {
    "Attributes": [
      {
        "Name": "sub",
        "Value": "<Cognito Username>"
      },
      {
        "Name": "email_verified",
        "Value": "true"
      },
      {
        "Name": "email",
        "Value": "<User email>"
      }
    ],
    "Enabled": true,
    "UserCreateDate": "Fri, 09 Oct 2020 17:39:20 GMT",
    "UserLastModifiedDate": "Fri, 09 Oct 2020 17:39:20 GMT",
    "UserStatus": "<Cognito Username>",
    "Username": "51bc4a5b-6615-4056-ad0a-e8ae515cb924"
  }
}
```

{% endtab %}

{% tab title="400 User already exists. " %}

```
{
    "Error": {
        "Code": "UsernameExistsException",
        "Message": "An account with the given email already exists.",
    },
    "ResponseMetadata": {
        "HTTPHeaders": {
            "connection": "keep-alive",
            "content-length": "96",
            "content-type": "application/x-amz-json-1.1",
            "date": "Fri, 09 Oct 2020 16:20:04 GMT",
            "x-amzn-errormessage": "An account with the given email already exists.",
            "x-amzn-errortype": "UsernameExistsException:",
            "x-amzn-requestid": "3fc92761-90a9-4a50-b728-a3a69cab4dc8",
        },
        "HTTPStatusCode": 400,
        "RequestId": "3fc92761-90a9-4a50-b728-a3a69cab4dc8",
        "RetryAttempts": 0,
    },
    "message": "An account with the given email already exists.",
}
```

{% endtab %}

{% tab title="403 You don't have a valid token from Cognito." %}

```
You don't have the permission to access the requested resource. It is either read-protected or not readable by the server.
```

{% endtab %}
{% endtabs %}

## Edit User

<mark style="color:orange;">`PUT`</mark> `/users/:id`

This endpoint allows you to create a new user. \*Requires admin role

#### Path Parameters

| Name | Type   | Description                                  |
| ---- | ------ | -------------------------------------------- |
| id   | string | Cognito ID (UUID) of the user to be updated. |

#### Headers

| Name           | Type   | Description                       |
| -------------- | ------ | --------------------------------- |
| Authentication | string | Authentication token from Cognito |

#### Request Body

| Name           | Type    | Description                                                                                                                                                                 |
| -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| date\_added    | string  | An iso date to be provided if you want to override the date the user was created. ISO format: "YYYY-MM-DD HH-MM-SS"                                                         |
| email          | string  | The users email address. Min. length: 8, max. length: 128                                                                                                                   |
| first\_name    | string  | The first name of the user. Only alphanumeric characters, white spaces and hyphens. Min. Length: 1, Max Length: 128                                                         |
| last\_name     | string  | The last name of the user. Only alphanumeric characters, white spaces and hyphens. Min. Length: 1, Max Length: 128                                                          |
| is\_coa\_staff | boolean | True if the user is part of the City of Austin, False otherwise. If this field is not provided, this is automatically set to True if the email ends with "@austintexas.gov" |
| status\_id     | integer | The status of the user, 0 for inactive, 1 for active.                                                                                                                       |
| title          | string  | The job position title of the user.                                                                                                                                         |
| workgroup      | string  | The workgroup name. Not empty, min length: 3, max length: 128. Allowed characters: a-z, A-Z, 0-9, and any of these special characters: \_-!@%^\~?.:&()\[]$                  |
| workgroup\_id  | integer | The workgroup\_id in the moped\_workgroup table in the database.                                                                                                            |
| password       | string  | The new user's password. Allowed characters: a-z, A-Z, 0-9, and any of these special characters: \_-!@%^*\~?.:&*()\[]$                                                      |
| roles          | array   | Array of strings, must be at least one value. It must be at least one of these values: "moped-admin", "moped-editor" or "moped-viewer"                                      |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Delete User

<mark style="color:red;">`DELETE`</mark> `/users/:id`

This endpoint allows you to delete a user. \*Requires admin role

#### Path Parameters

| Name | Type   | Description     |
| ---- | ------ | --------------- |
| id   | string | User Cognito ID |

#### Headers

| Name           | Type   | Description                       |
| -------------- | ------ | --------------------------------- |
| Authentication | string | Authentication token from Cognito |

{% tabs %}
{% tab title="200 User successfully deleted." %}

```
{
  "ResponseMetadata": {
    "HTTPHeaders": {
      "connection": "keep-alive",
      "content-length": "0",
      "content-type": "application/x-amz-json-1.1",
      "date": "Fri, 09 Oct 2020 17:25:02 GMT",
      "x-amzn-requestid": "833d74e7-6ad4-47b8-800f-2a279ceb2bbd"
    },
    "HTTPStatusCode": 200,
    "RequestId": "833d74e7-6ad4-47b8-800f-2a279ceb2bbd",
    "RetryAttempts": 0
  }
}
```

{% endtab %}

{% tab title="403 You don't have a valid token from Cognito." %}

```
You don't have the permission to access the requested resource. It is either read-protected or not readable by the server.
```

{% endtab %}
{% endtabs %}

## Update User Password

<mark style="color:orange;">`PUT`</mark> `/users/:id/password`

#### Path Parameters

| Name | Type   | Description     |
| ---- | ------ | --------------- |
| id   | string | User Cognito ID |

#### Headers

| Name           | Type   | Description                       |
| -------------- | ------ | --------------------------------- |
| Authentication | string | Authentication token from Cognito |

#### Request Body

| Name     | Type   | Description                                                                                                          |
| -------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| password | string | The new user's password. Allowed characters: a-z, A-Z, 0-9, and any of these special characters: \_-!@%^\~?.:&()\[]$ |

{% tabs %}
{% tab title="200 " %}

```
{
    "success": {
        "cognito": {
            "ResponseMetadata": {
                "HTTPHeaders": {
                    "connection": "keep-alive",
                    "content-length": "2",
                    "content-type": "application/x-amz-json-1.1",
                    "date": "Fri, 20 Nov 2020 22:54:09 GMT",
                    "x-amzn-requestid": "9580cdab-72ea-4048-a870-2b99bc045300"
                },
                "HTTPStatusCode": 200,
                "RequestId": "9580cdab-72ea-4048-a870-2b99bc045300",
                "RetryAttempts": 0
            }
        },
        "message": "User password updated: <User Cognito ID>"
    }
}
```

{% endtab %}

{% tab title="403 " %}

```
You don't have the permission to access the requrested resource. It is either read-protected or not readable by the server.
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://atd-dts.gitbook.io/moped-documentation/dev-guides/api/user-management-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.