介绍

爱速搭提供了开放 API，可以自动化控制爱速搭中的功能，方便进行系统对接。

安全校验

所有接口调用都需要进行签名校验，目前有两种级别的签名：

组织级别，可以访问组织下所有应用的 API
应用级别，只能访问某个应用的 API

在使用之前，首先需要设置公钥

设置组织级别公钥

访问组织「设置」页面，点选「OpenAPI 设置」，在公钥管理处，可以通过自己生成 RSA256 密钥对添加公钥，或者使用平台的自动生成功能。

标题：可以设置一个标识性的文本来区分使用方
公钥：点击自动生成的链接，会生成 xxx-key.zip 文件，请将其中 xxx.pub 的内容复制到该文本框，然后保存。
是否启用：可以设置当前公钥使用启用
可调用接口：可以设置当前公钥对应的签名，可以访问的接口，可以全部可访问，或者自定义可访问的接口

组织级别签名

签名算法使用 RS256，密钥是刚才下载的密钥，签名内容是 "companyKey": "xxx"，其中 xxx 是组织的短名字，可以在「设置」页面查到：

在发送 API 的请求中，需要有个 x-client-id 和 Authorization 的头。其中 x-client-id 在设置完 openAPI key 后，会自动生成一个，复制即可。而 Authorization 头则需要自行签名，签名生成算法基于 JWT，参考以下示例：

JavaScript 示例，使用 jsonwebtoken 进行签名。

const jwt = require('jsonwebtoken');
const fs = require('fs');
const privateKey = fs.readFileSync('company-xxx.key'); // 刚才下载的密钥，注意这里用的是密钥，不是公钥
const token = jwt.sign({companyKey: 'xxx'}, privateKey, {algorithm: 'RS256'}); // 将这里的 xxx 改成签名查到的短名字

// 接下来是发送 http 请求，在 header 中增加 Authorization，内容是「Bearer 」加上之前的生成的 token，这个 token 应该在每次提交的时候生成，为了避免重放攻击，默认 jwt 中会有 iat 时间戳，爱速搭会拒绝超过 1 分钟的签名
header['Authorization'] = 'Bearer ' + token;

JWT 支持绝大多数语言，具体可以在这里查找相关语言的库，比如 java 可以用 java-jwt，使用其中的 RSA256 算法。

设置应用级别公钥

应用级别公钥在应用的「应用设置」页面，同样也提供了自动生成功能。

标题：可以设置一个标识性的文本来区分使用方
公钥：点击自动生成的链接，会生成 xxx-key.zip 文件，请将其中 xxx.pub 的内容复制到该文本框，然后保存。
是否启用：可以设置当前公钥使用启用
可调用接口：可以设置当前公钥对应的签名，可以访问的接口，可以全部可访问，或者自定义可访问的接口

应用级别签名

签名算法使用 RS256，密钥是刚才下载的密钥，签名内容是 "companyKey": "xxx", "appKey": "yyy"，其中 xxx 是组织的短名字，看前面的介绍，而 yyy 是应用短名字，获取方法是在应用设置页：

Screen Shot.png

在发送 API 的请求中，需要有个 Authorization 的头，签名生成算法基于 JWT，参考以下示例：

JavaScript 示例，使用 jsonwebtoken 进行签名。

const jwt = require('jsonwebtoken');
const privateKey = fs.readFileSync('app-xxx.key'); // 这里要用应用级别的密钥
const token = jwt.sign({companyKey: 'xxx', appKey: 'yyy'}, privateKey, {
  algorithm: 'RS256'
}); // 请修改这里的 xxx 和 yyy

header['Authorization'] = 'Bearer ' + token;

JWT 支持绝大多数语言，具体可以在这里查找相关语言的库，比如 java 可以用 java-jwt，使用其中的 RSA256 算法。

java 和 go 语言的示例可以在 https://github.com/aisuda/aisuda-docs/tree/main/docs/OpenAPI/%E4%BB%A3%E7%A0%81%E7%A4%BA%E4%BE%8B 里找到。

发送提交参数

对于 POST 类型的接口，提交参数需要使用 JSON 格式。

以 axios 为例

axios({
  method: 'post',
  url: '/openapi/xxx',
  headers: {
    'Authorization': 'Bearer xx', // 前面生成的签名
    'x-client-id': '<your_client_id>' // 在 openApi 设置页面里面找
  },
  data: {
    name: 'isuda'
  }
});

安全校验​

设置组织级别公钥​

组织级别签名​

设置应用级别公钥​

应用级别签名​