---
# System prepended metadata

title: API

---

ESC - Permission - API

# API

### API 固定回傳格式

| 參數含意 | 參數名稱   | 說明  |
| -------- |:------ |:------- |
| 狀態 | status | 交易狀態代碼 |
| 回傳資料 | data | 依各自API回傳不同資料 |

status:
| 參數含意 | 參數名稱   | 參數類型 | 說明  |
| -------- |:------ |:------ |:------- |
| 狀態碼   | code | int   | 狀態碼  |
| 訊息     | messages | string   | 訊息 |

#### 回傳範例
```json=
{
    "status":{
        "code":200,
        "messages":"success"  
    },
    "data":{
        ...
    }
}
```

## 訊息代碼

| 代碼   | 說明                              | 適用API                 |
|:------ |:--------------------------------- |:----------------------- |
| 200    | 成功                              | 全部                    |
| 204000 | 缺少相關參數或值有誤              | 全部                    |
| 204030 | authorization認證失敗(basic auth) | [Auth](#Auth)           |
| 204040 | 資料不存在                        | [Role](#Role)           |
| 204130 | token相關驗證失敗(bearer token)   | 全部(排除[Auth](#Auth)) |
| 205000 | server非預期錯誤                  | 全部                    |


## Grant Type

| 參數 | 說明  | 
| -------- | -------- | 
| client_credentials     | Client Credentials Grant|
| refresh_token     | Refresh Access Token    |

## Auth 

### 請求方式

* `POST /v1/oauth/token
* `Header Authorization basic`

### Request

| 參數名稱   | 參數類型 | 參數含意                               | 必填 |
|:---------- |:-------- |:-------------------------------------- |:---- |
| grant_type | string   | 登入驗證流程 [Grant Type](#Grant-Type) | ✔️   |
| scope      | string   | 角色，多角色請用空格                   | ✔️   |

```json=
{
    "grant_type": "client_credential",
    "scope": "all"
}
```

### Header
|  參數名稱 | 參數類型 | 必填 | 備註 |
|-------- |:-------- |:---- |:---- |
| client_id    | string   | ✔️   |      |
| client_secret | string   | ✔️   |      |

    Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW


### Response
| 參數名稱      | 參數類型 | 參數含意                     | 必填 |
|:------------- |:-------- |:---------------------------- |:---- |
| access_token  | string   | oauth token                  | ✔️   |
| token_type    | int      | token header type            | ✔️   |
| expires_in    | int      | 多久過期(sec)                | ✔️   |
| refresh_token | int      | 用refresh_token交換新的token | ✔️   |

```json=
{
    "status": {
        "code": 200,
        "messages": "success"
    },
    "data": {
        "access_token": "4afb48e824debc713e8dd840c048fdb7f73cd3d5efa4d4a85a6f58365a27877b",
        "token_type": "Bearer",
        "expires_in": 3600,
        "refresh_token": "5ff579ca82516dae85d2167bb780ca23f92425d9182100854fa917b1fe9f5ed5"
    }
}
```

## Refresh Token 

### 請求方式

* `POST /v1/oauth/refresh`
* `Header Authorization Bearer Token`

### Request

| 參數名稱 | 參數類型 | 參數含意             | 必填 |
|:-------- |:-------- |:-------------------- |:---- |
| scope    | string   | 角色，多角色請用空格 | ✔️   |

```json=
{
    "scope": "all"
}
```

### Header
     Authorization: Bearer ac878c8a99121654a4fd8602eecfeed06a9eaa7b38b5aec6b378fd52381c8906


### Response
同[Auth](#ResponseData)

## 新增角色 

### 請求方式

* `POST /v1/role`
* `Header Authorization Bearer Token`

### Request

| 參數名稱    | 參數類型 | 參數含意             | 必填 |
|:----------- |:-------- |:-------------------- |:---- |
| name        | string   | 名稱                 | ✔️   |
| status      | int      | 狀態，1:啟用，2:禁用 | ✔️   |
| permissions | []string | 權限                 |      |

```json=
{
    "name": "test",
    "status": 1,
    "permissions": [
        "login",
        "select_role"
    ]
}
```

### Response
| 參數名稱    | 參數類型 | 參數含意            |
|:----------- |:-------- |:------------------- |
| name        | string   | 名稱                |
| uid        | string   | 角色                |
| status      | int      | 狀態 1:啟用，2:禁用 |
| permissions | []string | 權限                |

```json=
{
   "status":{
      "code":200,
      "messages":"success"
   },
   "data":{
      "name":"test",
      "uid":"AM000016",
      "permissions":[
         "login",
         "select_role"
      ],
      "status":1,
      "create_time":"2023-06-02T06:51:46Z",
      "update_time":"2023-06-02T06:51:46Z"
   }
}
```

## 編輯角色 

### 請求方式

* `PUT /v1/role/:uid`
* `Header Authorization Bearer Token`

### Request

| 參數名稱    | 參數類型 | 參數含意            |
|:----------- |:-------- |:------------------- |
| name        | string   | 名稱                |
| status      | int      | 狀態 1:啟用，2:禁用 |
| permissions | []string | 權限                |

```json=
{
    "name": "test",
    "status": 1,
    "permissions": [
        "login",
        "select_role"
    ]
}
```

### Response
| 參數名稱    | 參數類型 | 參數含意            |
|:----------- |:-------- |:------------------- |
| name        | string   | 名稱                |
| uid        | string   | 角色                |
| status      | int      | 狀態 1:啟用，2:禁用 |
| permissions | []string | 權限                |
```json=
{
   "status":{
      "code":200,
      "messages":"success"
   },
   "data":{
      "name":"test",
      "uid":"AM000016",
      "permissions":[
         "login",
         "select_role"
      ],
      "status":1,
      "create_time":"2023-06-02T06:51:46Z",
      "update_time":"2023-06-02T06:51:46Z"
   }
}
```


## 查看角色 

### 請求方式

* `GET /v1/role/:uid`
* `Header Authorization Bearer Token`

### Response
| 參數名稱    | 參數類型 | 參數含意            |
|:----------- |:-------- |:------------------- |
| name        | string   | 名稱                |
| uid        | string   | 角色                |
| status      | int      | 狀態 1:啟用，2:禁用 |
| permissions | []string | 權限                |

```json=
{
   "status":{
      "code":200,
      "messages":"success"
   },
   "data":{
      "name":"test",
      "uid":"AM000016",
      "permissions":[
         "login",
         "select_role"
      ],
      "status":1,
      "create_time":"2023-06-02T06:51:46Z",
      "update_time":"2023-06-02T06:51:46Z"
   }
}
```

## 所有角色 

### 請求方式

* `GET /v1/roles`
* `Header Authorization Bearer Token`

### Response
| 參數名稱    | 參數類型 | 參數含意            |
|:----------- |:-------- |:------------------- |
| name        | string   | 名稱                |
| uid        | string   | 角色                |
| status      | int      | 狀態 1:啟用，2:禁用 |
| permissions | []string | 權限                |

```json=
{
    "status": {
        "code": 200,
        "messages": "success"
    },
    "data": [
        {
            "name": "111",
            "uid": "AM000000",
            "permissions": [],
            "status": 1,
            "create_time": "2023-06-02T10:35:33Z",
            "update_time": "2023-06-05T10:24:58Z"
        },
        {
            "name": "tes1't",
            "uid": "AM000002",
            "permissions": [],
            "status": 1,
            "create_time": "2023-06-02T10:43:57Z",
            "update_time": "2023-06-05T10:35:24Z"
        }
    ]
}
```

## 角色列表 

### 請求方式

* `GET /v1/role`
* `Header Authorization Bearer Token`

### Request

| 參數名稱    | 參數類型 | 參數含意            |
|:----------- |:-------- |:------------------- |
| uid        | string   | 角色ID                |
| name        | string   | 名稱                |
| status      | int      | 狀態 1:啟用，2:禁用 |
| permissions | string | 權限，多筆用逗號間隔                |
| page_index | int | 頁數                |
| page_size | int | 每一頁多少筆                |


```
Query String

?uid=&name&permissions&status=1&page_index=1&page_size=2
```

### Response
| 參數名稱    | 參數類型 | 參數含意            |
|:----------- |:-------- |:------------------- |
| name        | string   | 名稱                |
| uid         | string   | 角色                |
| status      | int      | 狀態 1:啟用，2:禁用 |
| permissions | []string | 權限                |
| total       | int      | 總筆數              |
| page        | int      | 頁數                |
| size        | int      | 每一頁多少筆        |

```json=
{
    "status": {
        "code": 200,
        "messages": "success"
    },
    "data": {
        "list": [
            {
                "name": "test",
                "uid": "AM000000",
                "permissions": [],
                "status": 1,
                "create_time": "2023-06-02T10:35:33Z",
                "update_time": "2023-06-02T10:35:33Z"
            },
            {
                "name": "test",
                "uid": "AM000002",
                "permissions": [],
                "status": 1,
                "create_time": "2023-06-02T10:43:57Z",
                "update_time": "2023-06-02T10:43:57Z"
            }
        ],
        "page": 1,
        "total": 9,
        "size": 2
    }
}
```