# User Management API

![](https://1420082453-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MIQvl_rKnZ_-wHRdp4J%2F-MLEtso78LbjdAH3t2S3%2F-MLEz8W_-gZI3YVA4vlf%2F2020-11-03_15-21-21.png?alt=media\&token=9c99a002-e601-4e02-ae63-d491736c743f)

## 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 %}