Help Center/ Host Security Service/ API Reference/ API Description/ AI Defender/ Obtaining an access token (for common authentication). Currently, only CN Southwest-Guiyang1 and CN North-Beijing4 support this function.
Updated on 2026-09-24 GMT+08:00
View PDF
Share

Obtaining an access token (for common authentication). Currently, only CN Southwest-Guiyang1 and CN North-Beijing4 support this function.

Function

Obtaining an access token (for common authentication). The token is valid for 24 hours.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

  • If you are using role/policy-based authorization, see Permissions Policies and Supported Actions for details on the required permissions.
  • If you are using identity policy-based authorization, no identity policy-based permission required for calling this API.

URI

POST /v1/general/auth/token

Request Parameters

Table 1 Request body parameters

Parameter

Mandatory

Type

Description

install_key

Yes

String

Definition

Installing secrets

Constraints

Mandatory

Range

The format is ik_prefix + Random string.

Default Value

N/A

host_ip

Yes

String

Definition

Server IP address

Constraints

Mandatory. Private IP address of the server

Range

A valid IPv4 or IPv6 address

Default Value

N/A

hostname

Yes

String

Definition

Host name.

Constraints

Mandatory

Range

The value can contain 1 to 255 characters.

Default Value

N/A

mac_address

No

String

Definition

MAC address

Constraints

N/A

Range

The format is XX:XX:XX:XX:XX:XX (six groups of hexadecimal numbers separated by colons).

Default Value

N/A

gateway_port

Yes

Integer

Definition

Gateway port

Constraints

Mandatory

Range

1 ~ 65535

Default Value

N/A

gateway_mode

Yes

String

Definition

Gateway mode

Constraints

Mandatory

Range

  • local

  • remote

Default Value

N/A

gateway_bind

Yes

String

Definition

Gateway binding address

Constraints

Mandatory

Range

The value must be a valid IP address or domain name.

Default Value

N/A

container_id

No

String

Definition

Container ID, which is used to identify the agent running in the container environment.

Constraints

This parameter is optional. This parameter is available only in container scenarios.

Range

The value can contain 1 to 128 characters.

Default Value

N/A

cluster_id

No

String

Definition

Cluster ID

Constraints

This parameter is optional. This parameter is available only in cluster scenarios.

Range

The value can contain 1 to 128 characters.

Default Value

N/A

namespace_id

No

String

Definition

Namespace ID

Constraints

This parameter is optional. This parameter is available only in cluster scenarios.

Range

The value can contain 1 to 128 characters.

Default Value

N/A

pod_id

No

String

Definition

POD ID

Constraints

This parameter is optional. This parameter is available only in cluster scenarios.

Range

The value can contain 1 to 128 characters.

Default Value

N/A

Response Parameters

Status code: 201

Table 2 Response body parameters

Parameter

Type

Description

access_token

String

Definition

Access token in JWT format.

Range

The value can contain 1 to 32,768 characters.

agent_id

String

Definition

Unique ID of an agent, in UUID format. The value is obtained by calling the POST /v1/agent/auth/token API.

Range

The value is a string of 36 characters in the format of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (a hexadecimal string of 8-4-4-4-12).

expires_in

Long

Definition

Token validity (s)

Range

The minimum value is 60 and the maximum value is 604800 (7 days).

Example Requests

{
  "install_key" : "ik_x9y8z7w6v5u4t3s2r1q0p",
  "host_ip" : "192.168.1.100",
  "hostname" : "DESKTOP-ABC123",
  "mac_address" : "00:1A:2B:3C:4D:5E",
  "gateway_port" : 8080,
  "gateway_mode" : "local",
  "gateway_bind" : "127.0.0.1",
  "container_id" : "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
  "cluster_id" : "cluster-01abc",
  "namespace_id" : "ns-default",
  "pod_id" : "pod-abc123"
}

Example Responses

Status code: 201

{
  "access_token" : "eyJhbGciOiJIUzI1NiJ9.eyJyb2xlIjoiYWdlbnQiLCJpZCI6IjI0NGE5Y2YxLWJiYzctM2M1Ny04NDRhLTJmMjdmNTEzYTM0MCIsInN1YiI6Imh0dHAtdG9rZW4iLCJpc3MiOiJtYXN0ZXIiLCJpYXQiOjE3ODc5MDAyODksImV4cCI6MTc4Nzk4NjY5MH0.V4JHNED7k8d1ogKw4Mh9Fs1ZmWdOENFG1HXO5gIfh_0",
  "agent_id" : "244a9cf1-bbc7-3c57-844a-2f27f513a340",
  "expires_in" : 86400
}

Status Codes

Status Code

Description

201

Request succeeded.

Error Codes

See Error Codes.

Parent Topic: AI Defender