API - Auth
==========

## Contents

- [Notes](#notes)
- [Common error codes](#errcode)
- [Roles](#roles)
- [Service APIs](#service)
    - [`GET /version` Get service version](#get_version)
- [Auth APIs](#auth)
    - [`GET /auth/api/v1/auth/tokeninfo` Get token information](#get_auth_tokeninfo)
    - [`POST /auth/api/v1/auth/logout` Log-out the user](#post_auth_logout)
- [User information APIs](#user)
    - [`GET /auth/api/v1/user` Get user information](#get_user)
    - [`PATCH /auth/api/v1/user` Update user information](#patch_user)
- [User administration APIs](#admin)
    - [`POST /auth/api/v1/user` Create user](#post_admin_user)
    - [`GET /auth/api/v1/user/count` User count](#get_admin_user_count)
    - [`GET /auth/api/v1/user/list` User list](#get_admin_user_list)
    - [`GET /auth/api/v1/user/{userId}` Get user information](#get_admin_user)
    - [`PATCH /auth/api/v1/user/{userId}` Update user information](#patch_admin_user)
    - [`DELETE /auth/api/v1/user/{userId}` Delete user](#delete_admin_user)
- [Client administration APIs](#client)
    - [`POST /auth/api/v1/client` Create client](#post_client)
    - [`GET /auth/api/v1/client/count` Client count](#get_client_count)
    - [`GET /auth/api/v1/client/list` Client list](#get_client_list)
    - [`GET /auth/api/v1/client/{clientId}` Get client information](#get_client)
    - [`PATCH /auth/api/v1/client/{clientId}` Update client information](#patch_client)
    - [`DELETE /auth/api/v1/client/{clientId}` Delete client](#delete_client)
    - [`DELETE /auth/api/v1/client/user/{userId}` Delete user clients](#delete_client_user)

## <a name="notes"></a>Notes

All API requests (except `GET /version`) must have a **Authorization** header with a **Bearer** token.

- **Example**

    ```http
    GET /auth/api/v1/user HTTP/1.1
    Host: localhost
    Authorization: Bearer 766f29fa8691c81b749c0f316a7af4b7d303e45bf4000fe5829365d37caec2a4
    ```

All APIs may respond one of the following status codes:

- **200 OK**: The request is success with body.
- **204 No Content**: The request is success without body.
- **400 Bad Request**: The API request has something wrong.
- **401 Unauthorized**: The access token is invalid or expired.
- **403 Forbidden**: The user does not have the permission to operate APIs.
- **404 Not Found**: The resource (in path) does not exist.
- **500 Internal Server Error**: The server is crash or get an unknown error. You should respond to the system administrators to solve the problem.
- **503 Service Unavailable**: The server has something wrong. Please try again later.

All error responses have the following parameters in JSON format string:

- *string* `code`: The error code.
- *string* `message`: (**optional**) The error message.

- **Example**

    ```http
    HTTP/1.1 401 Unauthorized
    Access-Control-Allow-Origin: *
    Content-Type: application/json
    Content-Length: 70
    ETag: W/"43-Npr+dy47IJFtraEIw6D8mYLw7Ws"
    Date: Thu, 13 Jan 2022 07:46:09 GMT
    Connection: keep-alive

    {"code":"err_auth","message":"Invalid token: access token is invalid"}
    ```

## <a name="errcode"></a>Common error codes

The following are common error codes. The API specific error codes are listed in each API response documents.

- **401** `err_auth`: Authorization code error. Please refresh a new token.
- **503** `err_db`: Database operation error. Please try again later.
- **503** `err_intmsg`: Inter-service communication error. Please try again later.
- **404** `err_not_found`: The request resource (normally in path) not found.
- **400** `err_param`: Request input format error. Please check request parameters.
- **403** `err_perm`: Permission fail. This usually means that API requests with an invalid user role.
- **503** `err_rsc`: Resource allocation error. Please try again later.
- **500** `err_unknown`: Unknown error. This usually means that the server causes bugs or unexpected errors.

## <a name="roles"></a>Roles

This system supports the following roles:

- `admin`: The system administrator.
- `dev`: The 3rd party developer.
- `manager`: The system manager who can manage users' information.
- `service`: The web service.

**Normal user** means users without any roles.

# <a name="service"></a>Service APIs

## <a name="get_version"></a>Get service version

Get service name and version information.

    GET /version?
        q={query}

- *string* `q`: (**optional**) To query the specific information **in plain text**. You can use:
    - `name`: To query the service name.
    - `version`: To query current version.

#### Response

- **200 OK**: Version information. Parameters are:

    - *object* `data`:
        - *string* `name`: The service name.
        - *string* `version`: Current version.

    - **Example**

        ```json
        {
            "data": {
                "name": "sylvia-iot-auth",
                "version": "1.0.0"
            }
        }
        ```

    - **Example** when `q=name`:

        ```
        sylvia-iot-auth
        ```

    - **Example** when `q=version`:

        ```
        1.0.0
        ```

# <a name="auth"></a>Auth APIs

These APIs can be used by all users.

## <a name="get_auth_tokeninfo"></a>Get token information

Get token information.

    GET /auth/api/v1/auth/tokeninfo

#### Response

- **200 OK**: Token information. Parameters are:

    - *object* `data`:
        - *string* `userId`: User ID.
        - *string* `account`: User account.
        - *string* `name`: User display name.
        - *object* `roles`: Roles with `{role}:true/false` format.
        - *string* `clientId`: Associated client ID.
        - *string[]* `scopes`: Allowed scopes.

- **400, 401, 500, 503**: See [Notes](#notes).

## <a name="post_auth_logout"></a>Log-out the user

Log-out all the user's sessions with the access token.

    POST /auth/api/v1/auth/logout

#### Response

- **204, 400, 401, 500, 503**: See [Notes](#notes).

# <a name="user"></a>User information APIs

These APIs can be used by all users.

## <a name="get_user"></a>Get user information

Get user self information.

    GET /auth/api/v1/user

#### Response

- **200 OK**: User information. Parameters are:

    - *object* `data`:
        - *string* `account`: User account.
        - *string* `createdAt`: Creation time in RFC 3339 format.
        - *string* `modifiedAt`: Creation time in RFC 3339 format.
        - *string | null* `verifiedAt`: Verification time in RFC 3339 format.
        - *object* `roles`: (**present for special roles**) Roles.
        - *string* `name`: Display name.
        - *object* `info`: Other information.

    - **Example**

        ```json
        {
            "data": {
                "account": "michael-johnson@example.com",
                "createdAt": "2022-01-01T02:23:47.053Z",
                "modifiedAt": "2022-01-02T05:17:27.129Z",
                "validated": "2022-01-01T02:26:52.210Z",
                "name": "Michael",
                "info": {
                    "firstName": "Michael",
                    "lastName": "Johnson",
                    "phoneNumber": "0987654321"
                }
            }
        }
        ```

- **400, 401, 500, 503**: See [Notes](#notes).

## <a name="patch_user"></a>Update user information

Update user self information.

    PATCH /auth/api/v1/user

#### Additional HTTP Headers

    Content-Type: application/json

#### Parameters

- *object* `data`:
    - *string* `password`: (**optional**) User password.
    - *string* `name`: (**optional**) The display name.
    - *object* `info`: (**optional**) Other information.

- **Note**: You must give at least one parameter.

- **Example**

    ```json
    {
        "data": {
            "name": "Michael",
            "info": {
                "firstName": "Michael",
                "lastName": "Johnson",
                "address": "123, abc road, def city",
                "phoneNumber": "123456"
            }
        }
    }
    ```

#### Response

- **204 No Content**
- **400, 401, 500, 503**: See [Notes](#notes).

# <a name="admin"></a>User administration APIs

These APIs can be used by system administrators only, for managers except:

- `GET /auth/api/v1/user/count`
- `GET /auth/api/v1/user/list`
- `GET /auth/api/v1/user/{userId}`
- `PATCH /auth/api/v1/user/{userId}`: (limited)

## <a name="post_admin_user"></a>Create user

Create a user.

    POST /auth/api/v1/user

#### Additional HTTP Headers

    Content-Type: application/json

#### Parameters

- *object* `data`:
    - *string* `account`: User account. Must be **email address** format or the pattern `[A-Za-z0-9]{1}[A-Za-z0-9-_]*`. The account will be transformed to lowercase.
    - *string* `password`: Password.
    - *string* `name`: (**optional**) Display name.
    - *object* `info`: (**optional**) Other information.
- *string* `expiredAt`: (**optional**) Set the expiration time in RFC 3339 format. Without this value means this user is never expired and is verified immediately.

- **Example**

    ```json
    {
        "data": {
            "account": "michael-johnson@example.com",
            "password": "p@ssw0rD",
            "name": "Michael",
            "info": {
                "firstName": "Michael",
                "lastName": "Johnson",
                "phoneNumber": "0987654321"
            }
        },
        "expiredAt": "2022-01-02T02:23:47.053Z"
    }
    ```

#### Response

- **200 OK**: The user ID. Parameters are:

    - *object* `data`:
        - *string* `userId`: The ID of the created user.

    - **Example**

        ```json
        {
            "data": {
                "userId": "1641003827053-c2e84RJO"
            }
        }
        ```

- **400 Bad Request**: the special error codes are:
    - `err_auth_user_exist`: The account has been used.
- **401, 403, 500, 503**: See [Notes](#notes).

## <a name="get_admin_user_count"></a>User count

Get user list count.

    GET /auth/api/v1/user/count?
        account={specifiedAccount}&
        contains={word}

- *string* `account`: (**optional**) To search the specified account. This is case insensitive and excludes **contains**.
- *string* `contains`: (**optional**) To search accounts which contain the specified word. This is case insensitive.

#### Response

- **200 OK**: User list count. Parameters are:

    - *object* `data`:
        - *number* `count`: User list count.

    - **Example**

        ```json
        {
            "data": {
                "count": 2
            }
        }
        ```

- **400, 401, 403, 500, 503**: See [Notes](#notes).

## <a name="get_admin_user_list"></a>User list

Get user list.

    GET /auth/api/v1/user/list?
        account={specifiedAccount}&
        contains={word}&
        fields={displayFields}&
        offset={offset}&
        limit={limit}&
        sort={sortKeysAndOrders}&
        format={responseFormat}

- *string* `account`: (**optional**) To search the specified account. This is case insensitive and excludes **contains**.
- *string* `contains`: (**optional**) To search accounts which contain the specified word. This is case insensitive.
- *string* `fields`: (**optional**) To display more data fields with comma separated format. **expired**, **disabled** can be used. For example, `fields=expired,disabled`.
- *number* `offset`: (**optional**) Data offset. Default is **0**.
- *number* `limit`: (**optional**) Number of items to list. **0** to list all data. Default is **100**.
- *string* `sort`: (**optional**) To sort the result. Format is `key:[asc|desc]`. The key can be **account**, **created**, **modified**, **verified**, **name**. Default is **account:asc**.
- *string* `format`: (**optional**) Response body format. Default is array in the **data** field.
    - **array**: The response body is JSON array, not an object.

#### Response

- **200 OK**: An array that contains all users' information. Parameters are:

    - *object[]* `data`:
        - *string* `userId`: User ID.
        - *string* `account`: User account.
        - *string* `createdAt`: Creation time in RFC 3339 format.
        - *string* `modifiedAt`: Modification time in RFC 3339 format.
        - *string | null* `verifiedAt`: Verification time in RFC 3339 format.
        - *string | null* `expiredAt`: (**optional**) Expiration time in RFC 3339 format.
        - *string | null* `disabledAt`: (**optional**) Disabled time in RFC 3339 format.
        - *object* `roles`: Roles.
        - *string* `name`: Display name.
        - *object* `info`: Other information.

    - **Example**

        ```json
        {
            "data": [
                {
                    "userId": "1640921188987-x51FTVPD",
                    "account": "admin@example.com",
                    "createdAt": "2021-12-31T03:26:28.987Z",
                    "modifiedAt": "2021-12-31T03:26:28.987Z",
                    "verifiedAt": "2021-12-31T03:26:28.987Z",
                    "expiredAt": null,
                    "disabledAt": null,
                    "roles": {
                        "admin": true
                    },
                    "name": "System administrator",
                    "info": {
                        "phoneNumber": "1234567890"
                    }
                },
                {
                    "userId": "1641003827053-c2e84RJO",
                    "account": "michael-johnson@example.com",
                    "created": "2022-01-01T02:23:47.053Z",
                    "modifiedAt": "2022-01-02T05:17:27.129Z",
                    "validated": "2022-01-01T02:26:52.210Z",
                    "expiredAt": null,
                    "disabledAt": null,
                    "roles": {},
                    "name": "Michael",
                    "info": {
                        "firstName": "Michael",
                        "lastName": "Johnson",
                        "phoneNumber": "0987654321"
                    }
                }
            ]
        }
        ```

    - **Example (format=`array`)**

        ```json
        [
            {
                "userId": "1640921188987-x51FTVPD",
                "account": "admin@example.com",
                "createdAt": "2021-12-31T03:26:28.987Z",
                "modifiedAt": "2021-12-31T03:26:28.987Z",
                "verifiedAt": "2021-12-31T03:26:28.987Z",
                "expiredAt": null,
                "disabledAt": null,
                "roles": {
                    "admin": true
                },
                "name": "System administrator",
                "info": {
                    "phoneNumber": "1234567890"
                }
            }
        ]
        ```

- **400, 401, 403, 500, 503**: See [Notes](#notes).

## <a name="get_admin_user"></a>Get user information

Get the specified user information.

    GET /auth/api/v1/user/{userId}

- *string* `userId`: The specified user ID to get user information.

#### Response

- **200 OK**:

    - *object* `data`: An object that contains the user information. See [User administration APIs - User list](#get_admin_user_list).

- **400, 401, 403, 500, 503**: See [Notes](#notes).
- **404 Not Found**: The specified user does not exist.

## <a name="patch_admin_user"></a>Update user information

Update the specified user information.

    PATCH /auth/api/v1/user/{userId}

- *string* `userId`: The specified user ID to update user information.

#### Additional HTTP Headers

    Content-Type: application/json

#### Parameters

- *object* `data`: (**optional**)
    - *string* `verifiedAt`: (**optional for admin**) The validation date time in RFC 3339 format. The **expiredAt** field will be set to **null**.
    - *object* `roles`: (**optional**) Roles. The content must be booleans. Only administrators can set to roles **admin** and **service**.
    - *string* `password`: (**optional for admin**) User password.
    - *string* `name`: (**optional for admin**) The display name.
    - *object* `info`: (**optional for admin**) Other information. You must provide full of fields, or all fields will be replaced with the new value.
- *bool* `disable`: (**optional**) **true** to disable the user and **false** to enable the user. The permissions are:
    - **admin**: (all)
    - **manager**: service, user

- **Note**: You must give at least one parameter.

- **Example**

    ```json
    {
        "data": {
            "roles": {
                "developer": true
            },
            "info": {
                "firstName": "Michael",
                "lastName": "Johnson",
                "address": "123, abc road, def city",
                "phoneNumber": "123456"
            }
        },
        "disable": false
    }
    ```

#### Response

- **204 No Content**
- **400, 401, 403, 500, 503**: See [Notes](#notes).
- **404 Not Found**: The specified user does not exist.

## <a name="delete_admin_user"></a>Delete user

Delete a user. One cannot delete himself/herself.

    DELETE /auth/api/v1/user/{userId}

- *string* `userId`: The specified user ID to delete.

#### Response

- **204 No Content**
- **401, 403, 500, 503**: See [Notes](#notes).

# <a name="client"></a>Client administration APIs

These APIs can be used by system administrators and developers only, except:

- `DELETE /auth/api/v1/client/user/{userId}`: for administrators.

## <a name="post_client"></a>Create client

Create a client.

    POST /auth/api/v1/client

#### Additional HTTP Headers

    Content-Type: application/json

#### Parameters

- *object* `data`:
    - *string[]* `redirectUris`: Allowed redirect URIs.
    - *string[]* `scopes`: Allowed scopes in `[a-z0-9]+([\.]{1}[a-z0-9])*` format.
    - *string* `userId`: (**optional for administrators**) Assign to the specified user.
    - *string* `name`: Client name.
    - *string* `image`: (**optional**) The URI of the client icon.
- *boolean* `credentials`: (**optional**) Create the client with secret. Default is **false**.

#### Response

- **200 OK**: The client ID. Parameters are:

    - *object* `data`:
        - *string* `clientId`: The ID of the created client.

    - **Example**

        ```json
        {
            "data": {
                "clientId": "1641040728318-zyAnDK9I"
            }
        }
        ```

- **400 Bad Request**: the special error codes are:
    - `err_auth_user_not_exist`: The user ID does not exist.
- **401, 403, 500, 503**: See [Notes](#notes).

## <a name="get_client_count"></a>Client count

Get client list count.

    GET /auth/api/v1/client/count?
        user={userId}

- *string* `user`: (**optional for administrators**) The specified user ID.

#### Response

- **200 OK**: Client list count. Parameters are:

    - *object* `data`:
        - *number* `count`: Client list count.

    - **Example**

        ```json
        {
            "data": {
                "count": 2
            }
        }
        ```

- **400, 401, 403, 500, 503**: See [Notes](#notes).

## <a name="get_client_list"></a>Client list

Get client list.

    GET /auth/api/v1/client/list?
        user={userId}&
        offset={offset}&
        limit={limit}&
        sort={sortKeysAndOrders}&
        format={responseFormat}

- *string* `user`: (**optional for administrators**) The specified user ID.
- *number* `offset`: (**optional**) Data offset. Default is **0**.
- *number* `limit`: (**optional**) Number of items to list. **0** to list all data. Default is **100**.
- *string* `sort`: (**optional**) To sort the result. Format is `key:[asc|desc]`. The key can be **created**, **modified**, **name**. Default is **name:asc**.
- *string* `format`: (**optional**) Response body format. Default is array in the **data** field.
    - **array**: The response body is JSON array, not an object.

- **Note**: Administrators can get all clients and developers can only get their own clients.

#### Response

- **200 OK**: An empty array or an array that contains all clients' information. Parameters are:

    - *object* `data`:
        - *string* `clientId`: Client ID.
        - *string* `createdAt`: Creation time in RFC 3339 format.
        - *string* `modifiedAt`: Modification time in RFC 3339 format.
        - *string | null* `clientSecret`: Client secret. **null** means that this is a public client.
        - *string[]* `redirectUris`: Allowed redirect URIs.
        - *string[]* `scopes`: Allowed scopes.
        - *string* `userId`: (**optional for administrators**) User ID that is associated with the client.
        - *string* `name`: Client name.
        - *string | null* `image`: The URI of the client icon.

    - **Example**

        ```json
        {
            "data": [
                {
                    "clientId": "1641040728318-zyAnDK9I",
                    "createdAt": "2022-01-01T12:38:48.318Z",
                    "modifiedAt": "2022-01-01T12:38:48.318Z",
                    "clientSecret": "G3LCtKsJvB3nrkA4CnIH3IUVF+BKMHXHTXbzgNF6REU",
                    "redirectUris": [ "https://localhost/oauth2/desktop" ],
                    "scopes": [ "user.rw", "client.rw" ],
                    "name": "OAuth2 App",
                    "image": "https://localhost/oauth2/app.png"
                },
                {
                    "clientId": "1641042262366-1HTBqdPg",
                    "createdAt": "2022-01-01T13:04:22.366Z",
                    "modifiedAt": "2022-01-02T07:52:38.129Z",
                    "redirectUris": [ "https://exmaple.com/oauth2/redirect/uri" ],
                    "scopes": [ "user.rw", "client.rw" ],
                    "name": "OAuth2 Web",
                    "image": "https://example.com/oauth2/web.png"
                }
            ]
        }
        ```

    - **Example (format=`array`)**

        ```json
        [
            {
                "clientId": "1641040728318-zyAnDK9I",
                "createdAt": "2022-01-01T12:38:48.318Z",
                "modifiedAt": "2022-01-01T12:38:48.318Z",
                "clientSecret": "G3LCtKsJvB3nrkA4CnIH3IUVF+BKMHXHTXbzgNF6REU",
                "redirectUris": [ "https://localhost/oauth2/desktop" ],
                "scopes": [ "user.rw", "client.rw" ],
                "name": "OAuth2 App",
                "image": "https://localhost/oauth2/app.png"
            }
        ]
        ```

- **400, 401, 403, 500, 503**: See [Notes](#notes).

## <a name="get_client"></a>Get client information

Get the specified client information.

    GET /auth/api/v1/client/{clientId}

- *string* `clientId`: The specified client ID to get client information.

#### Response

- **200 OK**:

    - *object* `data`: An object that contains the client information. See [Client administration APIs - Client list](#get_client_list).

- **400, 401, 403, 500, 503**: See [Notes](#notes).
- **404 Not Found**: The specified client does not exist.

## <a name="patch_client"></a>Update client information

Update the specified client information.

    PATCH /auth/api/v1/client/{clientId}

- *string* `clientId`: The specified client ID to update client information.

#### Additional HTTP Headers

    Content-Type: application/json

#### Parameters

- *object* `data`: (**optional**)
    - *string[]* `redirectUris`: (**optional**) Allowed redirect URIs.
    - *string[]* `scopes`: (**optional**) Allowed scopes in `[a-z0-9]+([\.]{1}[a-z0-9])*` format.
    - *string* `name`: (**optional**) Client name.
    - *string | null* `image`: (**optional**) The URI of the client icon.
- *boolean* `regenSecret`: (**optional**) Re-generate secret of the private client. Default is **false**.

- **Note**: You must give at least one parameter.

- **Example**

    ```json
    {
        "data": {
            "name": "New client name"
        }
    }
    ```

#### Response

- **204 No Content**
- **400, 401, 403, 500, 503**: See [Notes](#notes).
- **404 Not Found**: The specified client does not exist.

## <a name="delete_client"></a>Delete client

Delete a client. One client cannot delete itself.

    DELETE /auth/api/v1/client/{clientId}

- *string* `clientId`: The specified client ID to delete.

#### Response

- **204 No Content**
- **400, 401, 403, 500, 503**: See [Notes](#notes).

## <a name="delete_client_user"></a>Delete user clients

Delete all clients of the specified user.

    DELETE /auth/api/v1/client/user/{userId}

- *string* `userId`: The specified user ID.

#### Response

- **204 No Content**
- **400, 401, 403, 500, 503**: See [Notes](#notes).