> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akool.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage

### Overview

OpenAPI supports two authentication methods. We **recommend using the direct API key method** for simplicity and better security.

#### Method 1: Direct API Key (Recommended)

The simplest way to authenticate is by using your API Key directly. Get your API Key from our API interfaces by clicking on the top API button on this page openAPI.

**Note:** In the frontend interface, this is displayed as "API Key", but in code implementation, it's the same value as your previous clientSecret.

1. Login to our website
2. Click API icon
3. Click "API Credentials" to generate your API Key
4. Use the API Key directly in your requests

All API requests should include your API Key in the HTTP header:

**Custom x-api-key header**

```
x-api-key: {API Key}
```

#### Method 2: ClientId/API Key (clientSecret) - Legacy Method

For backward compatibility, we also support the traditional clientId/clientSecret method:

**Note:** Your API Key (displayed in frontend) is the same value as your previous clientSecret. In code, you can reference it as either clientSecret or use the x-api-key header format.

1. Login to our website
2. Click API icon
3. Click "API Credentials" to set your key pair (clientId, API Key)
4. Use the clientId/API Key to obtain an access token via the `/getToken` endpoint
5. Use the obtained token in subsequent API calls

Bearer tokens are generally composed of a random string of characters. Formally, it takes the form of the "Bearer" keyword and the token value separated by spaces:

```
Authorization: Bearer {token}
```

Here is an example of an actual Bearer token:

```
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjYyYTA2Mjg1N2YzNWNjNTJlM2UxNzYyMCIsInR5cGUiOiJ1c2VyIiwiZnJvbSI6InRvYiIsImVtYWlsIjoiZ3VvZG9uZ2RvbmdAYWtvb2wuY29tIiwiZmlyc3ROYW1lIjoiZGQiLCJ1aWQiOjkwMzI4LCJjb2RlIjoiNTY1NCIsImlhdCI6MTczMjg2NzczMiwiZXhwIjoxNzMyODY3NzMzfQ._pilTnv8sPsrKCzrAyh9Lsvyge8NPxUG5Y_8CTdxad0
```

**Security Note:** Your API Key/token is secret! Do not share it with others or expose it in any client-side code (browser, application). Production requests must be routed through your own backend server, and your API Key can be securely loaded from environment variables or a key management service.

### API

#### Using Direct API Key (Recommended)

When using the direct API Key method, you can include your API Key in the HTTP headers using either format:

**Custom x-api-key header**

```
x-api-key: {your-api-key}
```

No additional token generation step is required. Your API Key serves as the authentication token directly.

#### Get Token (Legacy Method)

```
POST https://openapi.akool.com/api/open/v3/getToken
```

For users still using the clientId/API Key (clientSecret) method, use this endpoint to obtain an access token:

**Body Attributes**

| **Parameter** | **Description**                                                      |
| ------------- | -------------------------------------------------------------------- |
| clientId      | Used for request creation authorization                              |
| clientSecret  | Used for request creation authorization (same value as your API Key) |

**Response Attributes**

| **Parameter** | **Value** | **Description**                                      |
| ------------- | --------- | ---------------------------------------------------- |
| code          | 1000      | Interface returns business status code(1000:success) |
| token         |           | API token                                            |

<Note>Please note that the generated token is valid for more than 1 year.</Note>

#### Example

##### Direct API Key Usage (Recommended)

**Using x-api-key header**

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://openapi.akool.com/api/your-endpoint' \
  --header 'x-api-key: {{API Key}}' \
  --header 'Content-Type: application/json' \
  --data '{}'
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();
  MediaType mediaType = MediaType.parse("application/json");
  RequestBody body = RequestBody.create(mediaType, "");
  Request request = new Request.Builder()
    .url("https://openapi.akool.com/api/your-endpoint")
    .method("POST", body)
    .addHeader("x-api-key", "{{API Key}}")
    .addHeader("Content-Type", "application/json")
    .build();
  Response response = client.newCall(request).execute();
  ```

  ```js Javascript theme={null}
  const myHeaders = new Headers();
  myHeaders.append("x-api-key", "{{API Key}}");
  myHeaders.append("Content-Type", "application/json");

  const raw = JSON.stringify({});

  const requestOptions = {
    method: "POST",
    headers: myHeaders,
    body: raw,
    redirect: "follow"
  };

  fetch("https://openapi.akool.com/api/your-endpoint", requestOptions)
    .then((response) => response.text())
    .then((result) => console.log(result))
    .catch((error) => console.error(error));
  ```

  ```php PHP theme={null}
  <?php
  $client = new Client();
  $headers = [
    'x-api-key' =>'{{API Key}}',
    'Content-Type' => 'application/json'
  ];
  $body = '{}';
  $request = new Request('POST', 'https://openapi.akool.com/api/your-endpoint', $headers, $body);
  $res = $client->sendAsync($request)->wait();
  echo $res->getBody();
  ?>
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://openapi.akool.com/api/your-endpoint"

  payload = json.dumps({})
  headers = {
    'x-api-key':'{{API Key}}',
    'Content-Type': 'application/json'
  }

  response = requests.request("POST", url, headers=headers, data=payload)
  print(response.text)
  ```
</CodeGroup>

#### Legacy Token Generation Method

**Body**

```json theme={null}
{
  "clientId": "64db241f6d9e5c4bd136c187",
  "clientSecret": "openapi.akool.com"
}
```

**Request**

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://openapi.akool.com/api/open/v3/getToken' \
  --header 'Content-Type: application/json' \
  --data '{
    "clientId": "64db241f6d9e5c4bd136c187",
    "clientSecret": "openapi.akool.com"
  }'
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();
  MediaType mediaType = MediaType.parse("application/json");
  RequestBody body = RequestBody.create(mediaType, "{\r\n    \"clientId\": \"64db241f6d9e5c4bd136c187\",\r\n    \"clientSecret\": \"openapi.akool.com\"\r\n}");
  Request request = new Request.Builder()
    .url("https://openapi.akool.com/api/open/v3/getToken")
    .method("POST", body)
    .addHeader("Content-Type", "application/json")
    .build();
  Response response = client.newCall(request).execute();
  ```

  ```js Javascript theme={null}
  const myHeaders = new Headers();
  myHeaders.append("Content-Type", "application/json");

  const raw = JSON.stringify({
    "clientId": "64db241f6d9e5c4bd136c187",
    "clientSecret": "openapi.akool.com"
  });

  const requestOptions = {
    method: "POST",
    headers: myHeaders,
    body: raw,
    redirect: "follow"
  };

  fetch("https://openapi.akool.com/api/open/v3/getToken", requestOptions)
    .then((response) => response.text())
    .then((result) => console.log(result))
    .catch((error) => console.error(error));
  ```

  ```php PHP theme={null}
  <?php
  $client = new Client();
  $headers = [
    'Content-Type' => 'application/json'
  ];
  $body = '{
    "clientId": "64db241f6d9e5c4bd136c187",
    "clientSecret": "openapi.akool.com"
  }';
  $request = new Request('POST', 'https://openapi.akool.com/api/open/v3/getToken', $headers, $body);
  $res = $client->sendAsync($request)->wait();
  echo $res->getBody();
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://openapi.akool.com/api/open/v3/getToken"

  payload = json.dumps({
    "clientId": "64db241f6d9e5c4bd136c187",
    "clientSecret": "openapi.akool.com"
  })
  headers = {
    'Content-Type': 'application/json'
  }

  response = requests.request("POST", url, headers=headers, data=payload)

  print(response.text)
  ```
</CodeGroup>

**Response**

```json theme={null}
{
"code": 1000,
"token": "xxxxxxxxxxxxxxxx"
}
```

**Response Code Description**

<Note> Please note that if the value of the response code is not equal to 1000, the request is failed or wrong</Note>

| **Parameter** | **Value** | **Description**                                        |
| ------------- | --------- | ------------------------------------------------------ |
| code          | 1000      | Success                                                |
| code          | 1101      | Invalid authorization or The request token has expired |
| code          | 1102      | Authorization cannot be empty                          |
| code          | 1200      | The account has been banned                            |