法律声明

若接收烟台小樱桃网络科技有限公司（以下称为“小樱桃”）的此份文档，即表示您已同意以下条款。若不同意以下条款，请立即停止使用本文档。

本文档版权所有烟台小樱桃网络科技有限公司。保留任何未在本文档中明示授予的权利。文档中涉及小樱桃的专有信息。未经小樱桃事先书面许可，任何单位和个人不得复制、传递、分发、使用和泄漏该文档以及该文档包含的任何图片、表格、数据及其他信息。本网页版文档仅在xswitch.cn上发布。

本产品符合有关环境保护和人身安全方面的设计要求，产品的存放、使用和弃置应遵照产品手册、相关合同或相关国法律、法规的要求进行。

本文档按“现状”和“仅此状态”提供。本文档中的信息随着小樱桃的产品和技术的进步将不断更新，小樱桃不再通知此类信息的更新。

烟台小樱桃网络科技有限公司

地址：烟台市高新区蓝海路1号
邮编：264000
电话：0535-6753997

1 XSwitch认证鉴权接口

XUI支持通过API方式访问。根据安装部署方式的不同，可以使用不同的鉴权方式。

• 不鉴权：访问任何接口无需鉴权，适用于开发环境，以及可信的内部环境
• HTTP Basic：可以使用HTTP Basic方式鉴权
• HTTP Digest：未实现
• Session方式

本文讨论基于Session的认证方式。

通过认证API拿到Token后，即可携带Token访问有权限认证的接口。

1.1 登录

使用用户名密码获取Token。

1.1.1 获取Token

• 请求URL： /api/sessions
• 请求方式： POST
• 消息头：

• Body信息：

• 返回值：

正常返回一个JSON Object。

如果出错，返回HTTP状态码如403（用户名/密码错）500（内部错误）等。

• 其它说明：

首先，用用户名和密码获取一个TOKEN，参数的提交方式有两种，一种是基于URL字符串（www-form-urlencoded），如：

curl -XPOST -d 'login=1007&password=1234' 192.168.1.100:8081/api/sessions

也可以提交一个JSON请求，如：

curl -XPOST -d '{"login": "1007", "password": "1234"}' \
    -H "Content-Type: application/json" 192.168.1.100:8081/api/sessions

返回：

后续所有的请求（包括注销）都需要使用该Token。如

curl -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" 192.168.1.100:8081/api/users

也可以将该Key加入到Cookie中，如

freeswitch_xtra_session_id=62dd0173-4916-4b1c-b958-546e4d7c91fe

如上所见，Key与Cookie是通用的，所以，在Web界面上获取到的Cookie，也可以直接在API中使用，直到Cookie失效。

1.1.2 注销

• 请求URL： /api/sessions
• 请求方式： DELETE
• 消息头： 无
• Body信息：无
• 返回值：

正常返回一个Object。

• 示例：

curl -XDELETE -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" 192.168.1.100:8081/api/sessions

返回：

{"code":200, "text":"OK"}

2 开发Key

用户在集成调用XUI接口的过程中，需要Session ID作为验证身份的标识，对于开发者，可以申请一个永久有效的Session ID，申请途径有两种，一种是通过XUI Web界面登陆后去申请，另外一种是通过HTTP REST API。

2.1 Web方式

TODO

如图所示，每个用户登录后只能操作自己的开发key，申请后永久有效。当然申请后还可以查询和删除。

2.2 开发Key API说明

2.2.1 创建开发key

2.2.1.1 简要描述：

• 用户API客户端创建申请某一服务器的开发key，申请完永久有效。得到的Key可以直接做为上一节中的Token使用。

2.2.1.2 请求URL

POST http://host:port/api/users/dev_keys

2.2.1.3 参数：

• HEAD信息

• BODY信息

2.2.1.4 示例：

• cur例子：

curl -0 -H "Content-Type: application/json" --data \
    '{"username": "t13201", "password": "1234", "domain":"test.com"}' \
    -XPOST 192.168.1.100:8081/api/users/dev_keys

• 发送：

{
    "username" : "t13201",
    "password" : "1234",
    "domain" : "test.com"
}

• 返回：

{
    "data": {
        "description": "test",
        "updated_at": "2019-08-07 20:27:07",
        "key": "5bdd2cdd-fc64-47b1-b40e-f578d48b6d82",
        "deleted_at": "",
        "id": "20",
        "user_id": "35",
        "created_at": "2019-08-07 20:27:07"
    },
    "code": 200,
    "text": "success"
}

• 返回说明

• 状态码定义

2.2.2 删除开发key

用户API客户端删除自己的开发key

请求URL

DELETE http://host:port/api/users/dev_keys

参数：

• HEAD信息

2.2.2.1 示例：

• curl例子：

curl -0 -H "Content-Type: application/json" \
-H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" \
-XDELETE 192.168.1.100:8081/api/users/dev_keys

• 发送：

• 返回：

{
    "code": 0,
    "text": "sucess"
}

• 返回说明

• 状态码定义

2.2.3 查询开发key

2.2.3.1 简要描述：

• 用户API客户端查询自己的开发key列表 ###请求URL：

• http://host:port/api/users/dev_keys

2.2.3.2 参数：

• HEAD信息

2.2.3.3 示例：

• curl例子：

curl -0 -H "Content-Type: application/json" -GET \
  -H "X-XTRA-AUTH-ID: 62dd0173-4916-4b1c-b958-546e4d7c91fe" \
    192.168.1.100:8081/api/users/dev_keys

• 返回：

{
    "text": "success",
    "data": [{
        "created_at": "2019-08-06 20:13:06",
        "key": "62dd0173-4916-4b1c-b958-546e4d7c91fe",
        "id": "2",
        "description": "",
        "user_id": "35",
        "deleted_at": "",
        "updated_at": "2019-08-06 20:13:06"
    }, {
        "created_at": "2019-08-06 21:03:15",
        "key": "a09a4f9f-afc5-4eb9-bc32-db5fc4c75c7f",
        "id": "9",
        "description": "",
        "user_id": "35",
        "deleted_at": "",
        "updated_at": "2019-08-06 21:03:15"
    }],
    "code": 200
}

• 返回说明

• 状态码定义

3 Websocket

Websocket认证地址是/ws，在建立连接后进行认证。文档见JSON API相关文档。