所有用户必须使用 HTTPS 通过设备的配置端口访问 FXOS API。通常，所有 API 请求的基本 URL 如下所示：

https://<Firepower_Chassis_fqdn>[:management_port]/api/

Cisco 建议使用 Firepower 机箱完全限定域名 (chassis_fqdn) 而不是 IP 地址，以便 REST 客户端能够对受管设备进行身份验证；不过仍可使用 IP 地址。Firepower 机箱将使用提供的凭证对 REST 客户端进行身份验证。有关其他详细信息，请参阅客户端身份验证。

FXOS REST API 使用基于会话的身份验证方法，需要 HTTP TOKEN 报头才能对来自 API 客户端的每个请求进行身份验证。

除 /api/login 之外的所有 API 必须包括此 HTTP TOKEN 报头，TOKEN 值是 /api/login 响应中包含的实际令牌。如果未在 TOKEN 中指定令牌，REST API 将返回“需要身份验证”错误代码。

要获取身份验证令牌，API 客户端必须执行 POST /api/login 调用并使用以下 HTTP 报头：username: <name_of_user> password: <user_password>。

注	这些用户凭证必须已存在于机箱中，否则将返回“身份验证失败”错误。此外，如果用户密码为 URL 编码，则身份验证将失败。

成功的 /api/login 调用将返回 HTTP 200 代码并包含以下负载：

{
  "refreshPeriod": "string",
  "token": "string"
}

例如：

{
  "refreshPeriod": "0",
  "token": "a205739a4d56359730c08ee7bda559cd6e4dd36ad65bb10a17f71d4cea356028"
}

提交所有其他 API 方法请求时，必须提取此令牌并将其包含在 HTTP 报头中，并且令牌的报头字段名称必须为 TOKEN。

身份验证失败时，API 将返回 HTTP 400 代码并包含以下负载：{ "error-code": "551", "error-description": "Authentication failed", "error-nr": "unidentified-fail" }

身份验证失败时，如果令牌无效，API 将返回 HTTP 400 代码并包含以下负载：{ "error-code": "552", "error-description": "Authorization required", "error-nr": "service-unavailable" }

要进行注销，客户端必须提交 POST /api/logout 请求并包含以下 HTTP 报头："TOKEN"= "<authentication_token>"

找到会话并终止会话时，将返回 HTTP 200 代码。

如果未找到指定令牌的有效会话，将返回 HTTP 555 代码并包含以下负载：{ "error-code": "555", "error-description": "Authorization required", "error-nr": "service-unavailable" }

可使用以下 HTTP 方法：

• GET - 检索指定对象。查询在 URL 中提交，输出将包含在响应正文中。

• POST - 创建对象。路径在 URL 中提交，输出包含在响应正文中。

• PUT - 完全更新对象。如果未在负载中指定只读属性，则将忽略只读属性，并将可写属性设置为其默认值。如果未在请求负载中指定子对象，则将删除子对象（自动创建的对象除外）。

• PATCH - 部分更新在 URL 中指定的对象。仅更新指定对象的包含属性。其他现有属性将保留其以前的值。

• DELETE - 删除指定对象。

所有 REST API 客户端必须发送设置为 application/json 的 HTTP Accept 报头。否则，将返回 406 不可接受错误。

当上传 JSON 对象（POST 用于创建对象，PUT 用于更新对象）时，Content-type HTTP 报头必须设置为 application/json。否则，API 将返回 415 不支持的内容类型错误。当上传 Firepower 机箱基础设施捆绑包或 CSP 二进制文件时，REST API 客户端必须将 Content-type HTTP 报头设置为 multipart/binary。

执行 REST API 方法时，可能的 HTTP 错误代码如下：

• 200 - 成功并包含输出。方法成功，并返回同等 JSON 对象。

• 204 - 成功但输出为空。方法成功，但内容为空。

• 400 - 请求失败。请参阅错误消息了解详细信息。

• 403 - 禁止。权限被拒绝。不允许当前用户执行此操作。

• 404 - 未找到对象。未找到请求的对象。

• 405 - 方法不受支持。API 不支持请求的方法。

• 406 - 不可接受。当客户端请求 application/json 以外的任何内容时，返回此代码。

• 415 - 不支持的内容类型。当客户端发送 application/json 以外的任何内容类型时，返回此代码。

• 500 - 内部错误。API 在处理请求时遇到错误。