### Access API Interface with Access Token (curl)

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

This example shows how to access an API interface, such as getting a site list, using a previously obtained access token. The access token must be included in the Authorization header with the 'AccessToken=' prefix.

```curl
curl "https://localhost:8043/openapi/v1/de382a0e78f4deb681f3128c3e75dbd1/sites?pageSize=1&page=1" -H 'content-type:application/json' -H 'Authorization:AccessToken=AT-RCio7FS9p46wSD7dM8CwNQA7ylcrmAcV' -X GET -i -k --insecure
```

--------------------------------

### Omada Local Controller API Configuration and Example Call

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

This section explains how to configure the API_BASE for local Omada controllers, which may use custom domain names or IP addresses. It includes an example using `curl` to make an API call to a local controller, highlighting the need for the `-k` flag for self-signed certificates. The exact domain can be found in the Controller UI.

```bash
# Local controller uses custom domain/IP
# Example with localhost and custom port:
API_BASE="https://localhost:8043"

# Find exact domain via Controller UI:
# Settings > Platform Integration > Open API > View Application Details
# - OAuth Login Page Address: Frontend login URL
# - Interface Access Address: REST API base URL

# Example API call to local controller:
curl "https://192.168.1.100:8043/openapi/v1/{omadacId}/sites" \
  -H 'Authorization:AccessToken=AT-token' \
  -k
```

--------------------------------

### Node.js Express Webhook Receiver Example

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

Provides an example implementation of a webhook receiver using Node.js and the Express framework. This code demonstrates how to set up an endpoint to receive POST requests, verify the webhook authenticity using a secret key, and process the incoming notification data. It logs event details to the console and returns a 200 status upon successful processing.

```javascript
// Example webhook receiver (Node.js/Express)
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.json());

app.post('/webhook/omada', (req, res) => {
  const payload = req.body;
  const receivedSecret = payload.shardSecret;
  const expectedSecret = process.env.OMADA_WEBHOOK_SECRET;

  // Verify webhook authenticity
  if (receivedSecret !== expectedSecret) {
    console.error('Invalid webhook secret');
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Process webhook data
  console.log(`Event from site: ${payload.Site}`);
  console.log(`Controller: ${payload.Controller}`);
  console.log(`Timestamp: ${new Date(payload.timestamp).toISOString()}`);

  payload.text.forEach((logEntry, index) => {
    console.log(`[${index + 1}] ${logEntry}`);
  });

  res.status(200).json({ received: true });
});

app.listen(3000, () => {
  console.log('Omada webhook receiver running on port 3000');
});
```

--------------------------------

### Making Authenticated API Requests

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

Execute API operations by including the obtained access token in the 'Authorization' header. This section provides an example of how to retrieve a site list.

```APIDOC
## GET /openapi/v1/{omadacId}/sites

### Description
Retrieve a list of sites associated with a specific Omada controller.

### Method
GET

### Endpoint
/openapi/v1/{omadacId}/sites

### Parameters
#### Path Parameters
- **omadacId** (string) - Required - The ID of the Omada controller.

#### Query Parameters
- **pageSize** (integer) - Optional - The number of items to return per page.
- **page** (integer) - Optional - The page number to retrieve.

#### Request Body
None

### Request Example
```bash
curl "https://use1-omada-northbound.tplinkcloud.com/openapi/v1/de382a0e78f4deb681f3128c3e75dbd1/sites?pageSize=10&page=1" \
  -H 'content-type:application/json' \
  -H 'Authorization:AccessToken=AT-RCio7FS9p46wSD7dM8CwNQA7ylcrmAcV' \
  -X GET -k
```

### Response
#### Success Response (200)
- **errorCode** (integer) - Indicates success (0 for success).
- **msg** (string) - Success message.
- **result** (object) - Contains the site list details.
  - **totalRows** (integer) - Total number of sites available.
  - **currentPage** (integer) - The current page number.
  - **currentSize** (integer) - The number of sites on the current page.
  - **data** (array) - An array of site objects.
    - **siteId** (string) - The unique identifier for the site.
    - **name** (string) - The name of the site.
    - **region** (string) - The region where the site is located.
    - **timeZone** (string) - The time zone of the site.
    - **scenario** (string) - The scenario of the site (e.g., 'Hotel').
    - **type** (integer) - The type of the site.

#### Response Example
```json
{
  "errorCode": 0,
  "msg": "Success.",
  "result": {
    "totalRows": 1,
    "currentPage": 1,
    "currentSize": 1,
    "data": [
      {
        "siteId": "640effd1b3f2ae5b912275ec",
        "name": "Main Office",
        "region": "China mainland",
        "timeZone": "Asia/Shanghai",
        "scenario": "Hotel",
        "type": 0
      }
    ]
  }
}
```

**Important Notes:**
- **Authorization Header Format:** `Authorization: AccessToken={token_value}`
- **Rate Limit:** 10 requests per second per controller/organization.
```

--------------------------------

### Get Site List using curl

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

Retrieve a list of sites associated with an Omada controller. This requires an active access token, which should be included in the Authorization header. The request specifies pagination parameters like pageSize and page.

```bash
# Example: Get site list
curl "https://use1-omada-northbound.tplinkcloud.com/openapi/v1/de382a0e78f4deb681f3128c3e75dbd1/sites?pageSize=10&page=1" \
  -H 'content-type:application/json' \
  -H 'Authorization:AccessToken=AT-RCio7FS9p46wSD7dM8CwNQA7ylcrmAcV' \
  -X GET -k
```

--------------------------------

### Bash: Omada API Authorization Code Mode - Get Authorization Code

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

This bash snippet demonstrates the second step in obtaining an authorization code using the Authorization Code Mode flow. It uses `curl` to make a POST request to the `/openapi/authorize/code` endpoint, providing the `client_id`, `omadac_id`, and crucially, the `Csrf-Token` and `Cookie` obtained from the previous login step. The response contains the authorization `code`.

```bash
# Step 2: Obtain authorization code using session credentials
curl "https://use1-omada-northbound.tplinkcloud.com/openapi/authorize/code?client_id=29f2fdbeb5a84d50b9b1cdd08cd1a3ff&omadac_id=de382a0e78f4deb681f3128c3e75dbd1&response_type=code" \
  -H 'content-type:application/json' \
  -H 'Csrf-Token:51cb83c7d00a4e85b3dd2d6174a614d9' \
  -H 'Cookie:TPOMADA_SESSIONID=2fc0ca155ab94957a9a9e6a3b00662ea' \
  -X POST -k

# Response:
# {
#   "errorCode": 0,
#   "msg": "Open API Authorize successfully.",
#   "result": "OC-9iyxaKVOVMBpYhQ4NryaYBjghj3dTY32"
# }

# Note: Authorization code expires in 2 minutes
```

--------------------------------

### Bash: Create TP-Link Omada API Application

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

This bash script snippet demonstrates the steps to create a new Open API application within the TP-Link Omada Controller UI. It outlines the information required for both Authorization Code Mode and Client Credentials Mode, and highlights the credentials obtained after application creation, such as Client ID, Client Secret, and Omada ID.

```bash
# Navigate to Settings > Platform Integration in the Omada Controller UI
# Create new application with either:
# 1. Authorization Code Mode - requires Application name and Redirect URL
# 2. Client Credentials Mode - requires Application name and access permissions

# After creation, note the following from the application details:
# - Client ID: 38f2d1b616434374b3f3215246f39940
# - Client Secret: cf6b13af0dd045628c9f05f088eb5493
# - Omada ID: beed48c7a2b0ea97c9698408843119f3
# - OAuth Login Page: https://use1-omada-controller.tplinkcloud.com/openapi/authorize/login
# - API Access Address: https://use1-omada-northbound.tplinkcloud.com
```

--------------------------------

### Obtain Access Token

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

Obtains an access token using an authorization code. This is the initial step for authentication.

```APIDOC
## POST /openapi/authorize/token

### Description
Obtains an access token using an authorization code. This is the initial step for authentication.

### Method
POST

### Endpoint
/openapi/authorize/token

### Parameters
#### Query Parameters
- **grant_type** (string) - Required - The grant type, must be set to "authorization_code".

#### Request Body
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.

### Request Example
```json
{
  "client_id": "29f2fdbeb5a84d50b9b1cdd08cd1a3ff",
  "client_secret": "cf6b13af0dd045628c9f05f088eb5493"
}
```

### Response
#### Success Response (200)
- **accessToken** (string) - The obtained access token.
- **tokenType** (string) - The type of token, usually "bearer".
- **expiresIn** (integer) - The expiration time of the token in seconds.
- **refreshToken** (string) - A token to refresh the access token when it expires.

#### Response Example
```json
{
  "errorCode": 0,
  "msg": "Open API Get Access Token successfully.",
  "result": {
    "accessToken": "AT-bllLYOOYASck11SBSDmmHs85lCrkN6Gi",
    "tokenType": "bearer",
    "expiresIn": 7200,
    "refreshToken": "RT-HqvaDuSxEqayM75U2ukTRnBl6f6fiRAc"
  }
}
```
```

--------------------------------

### Omada Open API - Authentication Process

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

Details on how to authenticate with the Omada Open API using OAuth 2.0, including Authorization Code and Client Credentials flows.

```APIDOC
## 1.3 Process Introduction

Omada's Open API supports the REST API of most Controller services. This feature allows Omada users to write custom applications, embed APIs, or combine their own applications. The REST API supports HTTP GET and POST operations by providing specific URLs for each query. The output of these operations is returned in JSON format. To access the API securely, the Omada API framework supports the OAuth 2.0 protocol for authentication and authorization, which allows you to access resources authorized by users without obtaining user names and passwords, and supports the authorization code mode and client credentials mode.

### Authorization Code Mode
The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients. Since this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the authorization server.

**Process:**
1. The user visits the client.
2. The client directs the user to the authentication server (Omada).
3. User logs in (/openapi/login), and authorize the third-party client.
4. The authentication server directs the user to the redirection URL specified by the client in advance, and attaches an authorization code (redirect URL + ?code={authorization code}, if the redirect URL is https://redirect.com, it is https://redirect.com?code=authCode).
5. The client uses the authorization code to exchange the accessToken from the authentication server (Omada).
6. The authentication server (Omada) authenticates the client and issues an access token.
7. The client uses the access token to apply for resources from the resource server (Omada).
8. The resource server (Omada) confirms the access token and opens resources to the client.
9. The client can exchange an access token through refresh token, client ID, and client secret.

### Client Credentials Mode
The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control, or those of another resource owner that have been previously arranged with the authorization server (the method of which is beyond the scope of this specification).

**Process:**
1. The user opens the client, and the client requires the user to authorize.
2. The user agrees to authorize the client.
3. The client uses the authorization obtained to apply for an access token from the authentication server (Omada).
4. The authentication server (Omada) authenticates the client and issues an access token.
5. The client uses the access token to apply for resources from the resource server (Omada).
6. The resource server (Omada) confirms the access token and open resources to the client.
7. The client can exchange an access token through refresh token, client ID, and client secret.
```

--------------------------------

### Omada Open API - Status Codes

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

A list of common HTTP status codes and their explanations relevant to the Omada Open API.

```APIDOC
## 1.1 Status Code

**Status Code** | Explain
---|---
**400** | Bad Request
**401** | Unauthorized access
**403** | Forbidden
**413** | Request-size limit exceeded
**417** | Request-size limit exceeded
**429** | API Rate limit exceeded
**500** | Internal server error
```

--------------------------------

### Omada API Login Request (cURL)

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

This cURL command demonstrates how to log in to the Omada Open API. It requires the client ID, Omada ID, username, and password. The response contains a csrfToken and sessionId for subsequent requests. Ensure correct content-type and method are used.

```bash
curl "https://localhost:8043/openapi/authorize/login?client_id=38f2d1b616434374b3f3215246f39940&omadac_id=beed48c7a2b0ea97c9698408843119f3" -H 'content-type:application/json' -d '{"username":"admin","password":"tplink123"}' -X POST -i -k --insecure
```

--------------------------------

### Login Authentication & Obtain Authorization Code

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

This section details the process of authenticating a user and obtaining an authorization code using the Omada Northbound API, covering scenarios with and without a specified redirect URL.

```APIDOC
## POST /openapi/authorize/login

### Description
Logs in a user and obtains session tokens required for subsequent API calls. This is the first step in the authorization code grant flow.

### Method
POST

### Endpoint
/openapi/authorize/login

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The client ID of the application.
- **omadac_id** (string) - Required - The MSP ID or Customer ID.

#### Request Body
- **username** (string) - Required - The username for login.
- **password** (string) - Required - The password for login.

### Request Example
```json
{
  "username": "admin",
  "password": "tplink123"
}
```
```bash
curl "https://localhost:8043/openapi/authorize/login?client_id=38f2d1b616434374b3f3215246f39940&omadac_id=beed48c7a2b0ea97c9698408843119f3" -H 'content-type:application/json' -d '{"username":"admin","password":"tplink123"}' -X POST -i -k --insecure
```

### Response
#### Success Response (200)
- **csrfToken** (string) - The CSRF token for subsequent requests.
- **sessionId** (string) - The session ID for subsequent requests.

#### Response Example
```json
{
  "errorCode": 0,
  "msg": "Open API Log in successfully.",
  "result": {
    "csrfToken": "51cb83c7d00a4e85b3dd2d6174a614d9",
    "sessionId": "2fc0ca155ab94957a9a9e6a3b00662ea"
  }
}
```

## POST /openapi/authorize/code

### Description
Obtains an authorization code after successful login. This code is short-lived and used to exchange for an access token.

### Method
POST

### Endpoint
/openapi/authorize/code

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The client ID of the application.
- **omadac_id** (string) - Required - The MSP ID or Customer ID.
- **response_type** (string) - Required - Must be set to "code".

#### Headers
- **Csrf-Token** (string) - Required - The CSRF token obtained from the login step.
- **Cookie** (string) - Required - The session cookie, prefixed with "TPOMADA_SESSIONID=".

### Request Example
```bash
curl "https://localhost:8043/openapi/authorize/code?client_id=29f2fdbeb5a84d50b9b1cdd08cd1a3ff&omadac_id=de382a0e78f4deb681f3128c3e75dbd1&response_type=code" -H 'content-type:application/json' -H 'Csrf-Token:ae6b935c92cf4b1b9f3eb852e20ed2b8' -H 'Cookie:TPOMADA_SESSIONID=9cb86bf3a99e48a59e4f3bb464a3c443' -X POST -i -k --insecure
```

### Response
#### Success Response (200)
- **result** (string) - The authorization code.

#### Response Example
```json
{
  "errorCode": 0,
  "msg": "Open API Authorize successfully.",
  "result": "OC-9iyxaKVOVMBpYhQ4NryaYBjghj3dTY32"
}
```

## GET /oauth/authorize

### Description
Initiates the OAuth 2.0 authorization code flow when a redirect URL is specified. The user is redirected to a customized login page, and upon successful login, is redirected back to the specified redirect URL with the authorization code as a query parameter.

### Method
GET

### Endpoint
/oauth/authorize

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The client ID of the application.
- **redirect_uri** (string) - Optional - The URL to redirect to after successful authorization.
- **response_type** (string) - Required - Must be set to "code".
- **scope** (string) - Optional - Defines the permissions requested.

### Response
#### Success Response (302 Found)
Redirects the user to the specified `redirect_uri` with the authorization code:
`http://your-redirect-url.com?code={authorization_code}`

### Note
If you need to redirect the authorization code, please contact Omada technical support to add your domain name to the trusted list of the Omada system.
```

--------------------------------

### Omada Open API - Rate Limits

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

Information regarding the rate limits for accessing the Omada Open API.

```APIDOC
**Note** :
1. Each Omada Pro controller and each Omada organization has an API call budget of **10 requests per second**.
2. Most interface has a concurrency limit. We recommend that you modify global configurations before other configurations of the site.
```

--------------------------------

### Access API Interface

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

Accesses API interfaces after obtaining an access token. The access token must be included in the Authorization header.

```APIDOC
## GET /openapi/v1/{clientId}/sites

### Description
Accesses API interfaces after obtaining an access token. The access token must be included in the Authorization header.

### Method
GET

### Endpoint
/openapi/v1/{clientId}/sites

### Parameters
#### Path Parameters
- **clientId** (string) - Required - The client ID associated with the access token.

#### Query Parameters
- **pageSize** (integer) - Optional - The number of items to return per page.
- **page** (integer) - Optional - The page number to retrieve.

#### Headers
- **Authorization** (string) - Required - The access token in the format "AccessToken=YOUR_ACCESS_TOKEN".

### Request Example
```bash
curl "https://localhost:8043/openapi/v1/de382a0e78f4deb681f3128c3e75dbd1/sites?pageSize=1&page=1" \
  -H 'content-type:application/json' \
  -H 'Authorization:AccessToken=AT-RCio7FS9p46wSD7dM8CwNQA7ylcrmAcV' \
  -X GET -i -k --insecure
```

### Response
#### Success Response (200)
- **totalRows** (integer) - The total number of rows available.
- **currentPage** (integer) - The current page number.
- **currentSize** (integer) - The number of items on the current page.
- **data** (array) - An array of site objects.
  - **siteId** (string) - The ID of the site.
  - **name** (string) - The name of the site.
  - **region** (string) - The region of the site.
  - **timeZone** (string) - The time zone of the site.
  - **scenario** (string) - The scenario of the site.
  - **type** (integer) - The type of the site.

#### Response Example
```json
{
  "errorCode": 0,
  "msg": "Success.",
  "result": {
    "totalRows": 1,
    "currentPage": 1,
    "currentSize": 1,
    "data": [
      {
        "siteId": "640effd1b3f2ae5b912275ec",
        "name": "323233232",
        "region": "China mainland",
        "timeZone": "UTC",
        "scenario": "Hotel",
        "type": 0
      }
    ]
  }
}
```
```

--------------------------------

### Obtain Access Token via Authorization Code (curl)

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

This snippet demonstrates how to obtain an access token using the authorization code grant type via a curl command. It requires the grant type, authorization code, client ID, and client secret as parameters.

```curl
curl "https://localhost:8043/openapi/authorize/token?grant_type=authorization_code&code=OC-y8fyWAyICCqCWw44Oi9GeSr7fQIKHg7g" -H 'content-type:application/json' -d '{"client_id": "29f2fdbeb5a84d50b9b1cdd08cd1a3ff", "client_secret": "cf6b13af0dd045628c9f05f088eb5493"}' -X POST -i -k --insecure
```

--------------------------------

### Omada API Base URLs by Region

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

Defines the API base URLs for different geographical regions where Omada controllers are deployed. These URLs are crucial for directing API requests to the correct controller instance. The specific region can be verified in the Controller UI under Settings > Platform Integration > Open API.

```bash
API_BASE="https://aps1-omada-northbound.tplinkcloud.com"

# Europe
API_BASE="https://euw1-omada-northbound.tplinkcloud.com"

# US (example region)
API_BASE="https://use1-omada-northbound.tplinkcloud.com"
```

--------------------------------

### Omada Open API - General Error Codes

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

A list of general error codes returned in the API result and their explanations.

```APIDOC
## 1.2 General Error Code In Result

**Error Code** | Explain
---|---
**-1005** | Operation forbidden
**-1505** | The current user does not have permissions to access this site
**-44106** | The client id or client secret is invalid
**-44107** | The response type is invalid
**-44108** | The CSRF token is invalid
**-44109** | The session id is invalid
**-44110** | The auth code has expired
**-44111** | The grant type is invalid
**-44112** | The access token has expired. Please re-initiate the refreshToken process to obtain the access token.
**-44113** | The access token is Invalid
**-44114** | The refresh token has expired. Please re-initiate the authentication process to obtain the refresh token.
**-44116** | Open API authorized failed, please check whether the input parameters are legal.
**-44118** | This interface only supports the authorization code mode, not the client credentials mode.
```

--------------------------------

### Omada Webhook Message Format

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

Illustrates the structure of webhook messages sent by Omada controllers for audit logs and system events. It includes fields like 'Site', 'description', 'shardSecret' for verification, 'text' containing event details, 'Controller' identifier, and a 'timestamp'.

```json
{
  "Site": "Main Office",
  "description": "This is a webhook message from Omada Controller",
  "shardSecret": "your_webhook_secret_key_here",
  "text": [
    "User admin logged in from IP 192.168.1.100",
    "Device EAP660HD (00:11:22:33:44:55) connected"
  ],
  "Controller": "USA-Production",
  "timestamp": 1692128478856
}
```

--------------------------------

### Batch Process Multiple API Requests using curl (MSP)

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

Execute multiple API operations in a single batch request, supporting both MSP (Managed Service Provider) and customer-level operations. This allows for requests across different customers if authorized. A maximum of 20 operations can be batched.

```bash
# MSP batch operations (supports both MSP and customer-level operations)
curl "https://use1-omada-northbound.tplinkcloud.com/openapi/v1/msp/batch" \
  -H 'content-type:application/json' \
  -H 'Authorization:AccessToken=AT-RCio7FS9p46wSD7dM8CwNQA7ylcrmAcV' \
  -d '{
    "operations": [
      {
        "method": "GET",
        "url": "/openapi/v1/msp/{mspId}/customers",
        "params": {"pageSize": 10}
      },
      {
        "method": "GET",
        "url": "/openapi/v1/{customerId}/sites",
        "params": {"pageSize": 10}
      }
    ]
  }' \
  -X POST -k
```

--------------------------------

### Authentication - Authorization Code Mode: Login and Obtain Authorization Code

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

This section describes the process of logging in with user credentials and obtaining an authorization code, which is a prerequisite for exchanging it for an access token in delegated access scenarios.

```APIDOC
## POST /openapi/authorize/login

### Description
Logs in a user with provided credentials to obtain session information required for subsequent authorization steps.

### Method
POST

### Endpoint
https://use1-omada-northbound.tplinkcloud.com/openapi/authorize/login

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The client ID of the registered Open API application.
- **omadac_id** (string) - Required - The unique identifier for the Omada Controller instance.

#### Request Body
- **username** (string) - Required - The username for logging into the Omada Controller.
- **password** (string) - Required - The password for the Omada Controller user.

### Request Example
```json
{
  "username": "admin",
  "password": "tplink123"
}
```

### Response
#### Success Response (200)
- **errorCode** (integer) - 0 indicates success.
- **msg** (string) - A message indicating the status of the login operation.
- **result** (object) - Contains session-related information:
  - **csrfToken** (string) - A CSRF token for securing subsequent requests.
  - **sessionId** (string) - A session ID for authenticating the user's session.

#### Response Example
```json
{
  "errorCode": 0,
  "msg": "Open API Log in successfully.",
  "result": {
    "csrfToken": "51cb83c7d00a4e85b3dd2d6174a614d9",
    "sessionId": "2fc0ca155ab94957a9a9e6a3b00662ea"
  }
}
```

## POST /openapi/authorize/code

### Description
Obtains an authorization code using the session credentials obtained from the login step. This code is used to request an access token.

### Method
POST

### Endpoint
https://use1-omada-northbound.tplinkcloud.com/openapi/authorize/code

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The client ID of the registered Open API application.
- **omadac_id** (string) - Required - The unique identifier for the Omada Controller instance.
- **response_type** (string) - Required - Must be set to "code".

#### Request Headers
- **Csrf-Token** (string) - Required - The CSRF token obtained from the login step.
- **Cookie** (string) - Required - The session cookie containing the session ID (e.g., `TPOMADA_SESSIONID=...`).

### Response
#### Success Response (200)
- **errorCode** (integer) - 0 indicates success.
- **msg** (string) - A message indicating the status of the authorization code request.
- **result** (string) - The authorization code. This code expires in 2 minutes.

#### Response Example
```json
{
  "errorCode": 0,
  "msg": "Open API Authorize successfully.",
  "result": "OC-9iyxaKVOVMBpYhQ4NryaYBjghj3dTY32"
}
```
```

--------------------------------

### Obtain Access Token using Client Credentials (curl)

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

This snippet demonstrates how to obtain an access token using the client credentials grant type via a curl command. It requires specifying the grant type, omadacId, client_id, and client_secret in the request. The response includes the access token, token type, expiration, and refresh token.

```curl
curl "https://localhost:8043/openapi/authorize/token?grant_type=client_credentials" -H 'content-type:application/json' -d '{"omadacId": "de382a0e78f4deb681f3128c3e75dbd1", "client_id": "185586e0df424f5ea938de13cba91e01", "client_secret": "767372a5258a4fc1a03c57f3d071fc35"}' -X POST -i -k --insecure
```

--------------------------------

### Bash: Omada API Client Credentials Mode - Direct Token Acquisition

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

This bash snippet illustrates how to obtain an access token directly using Client Credentials Mode via `curl`. It sends a POST request to the `/openapi/authorize/token` endpoint with `grant_type=client_credentials`, including the `omadacId`, `client_id`, and `client_secret`. This method is suitable for application-level access without user interaction. The response provides an `accessToken` valid for 2 hours and a `refreshToken`.

```bash
curl "https://use1-omada-northbound.tplinkcloud.com/openapi/authorize/token?grant_type=client_credentials" \
  -H 'content-type:application/json' \
  -d '{
    "omadacId": "de382a0e78f4deb681f3128c3e75dbd1",
    "client_id": "185586e0df424f5ea938de13cba91e01",
    "client_secret": "767372a5258a4fc1a03c57f3d071fc35"
  }' \
  -X POST -k

# Response:
# {
#   "errorCode": 0,
#   "msg": "Open API Get Access Token successfully.",
#   "result": {
#     "accessToken": "AT-bjaJkIMIiekZY6NBufoQO4hdmJTswlwU",
#     "tokenType": "bearer",
#     "expiresIn": 7200,
#     "refreshToken": "RT-3ZjJgcORJSh76UCh7pj0rs5VRISIpagV"
#   }
# }

# Warning: Token becomes invalid if sites are copied/imported or application
# permissions change (role/site/customer privileges) - requires re-authentication
```

--------------------------------

### Authentication - Client Credentials Mode: Direct Token Acquisition

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

This endpoint allows applications to directly obtain an access token using their client ID and client secret, suitable for machine-to-machine communication without user interaction.

```APIDOC
## POST /openapi/authorize/token (Grant Type: client_credentials)

### Description
Acquires an access token directly using the application's client credentials. This method is used for server-to-server authentication where user authorization is not required.

### Method
POST

### Endpoint
https://use1-omada-northbound.tplinkcloud.com/openapi/authorize/token

### Parameters
#### Query Parameters
- **grant_type** (string) - Required - Must be set to "client_credentials".

#### Request Body
- **omadacId** (string) - Required - The unique identifier for the Omada Controller instance.
- **client_id** (string) - Required - The client ID of the registered Open API application.
- **client_secret** (string) - Required - The client secret of the registered Open API application.

### Request Example
```json
{
  "omadacId": "de382a0e78f4deb681f3128c3e75dbd1",
  "client_id": "185586e0df424f5ea938de13cba91e01",
  "client_secret": "767372a5258a4fc1a03c57f3d071fc35"
}
```

### Response
#### Success Response (200)
- **errorCode** (integer) - 0 indicates success.
- **msg** (string) - A message indicating the status of the token acquisition.
- **result** (object) - Contains token details:
  - **accessToken** (string) - The access token for authenticating API requests. Valid for 2 hours.
  - **tokenType** (string) - The type of the token, typically "bearer".
  - **expiresIn** (integer) - The lifetime of the access token in seconds (e.g., 7200).
  - **refreshToken** (string) - The refresh token used to obtain new access tokens. Valid for 14 days.

#### Response Example
```json
{
  "errorCode": 0,
  "msg": "Open API Get Access Token successfully.",
  "result": {
    "accessToken": "AT-bjaJkIMIiekZY6NBufoQO4hdmJTswlwU",
    "tokenType": "bearer",
    "expiresIn": 7200,
    "refreshToken": "RT-3ZjJgcORJSh76UCh7pj0rs5VRISIpagV"
  }
}
```

**Warning**: The token may become invalid if sites are copied/imported or application permissions change. Re-authentication is required in such cases.
```

--------------------------------

### Batch Process Multiple API Requests using curl (Non-MSP)

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

Execute multiple API operations within a single batch request. This non-MSP version requires all operations to target the same Omada controller (omadacId). Up to 20 operations can be included in a single batch.

```bash
# Non-MSP batch operations (same omadacId required for all operations)
curl "https://use1-omada-northbound.tplinkcloud.com/openapi/v1/batch" \
  -H 'content-type:application/json' \
  -H 'Authorization:AccessToken=AT-RCio7FS9p46wSD7dM8CwNQA7ylcrmAcV' \
  -d '{
    "operations": [
      {
        "method": "GET",
        "url": "/openapi/v1/de382a0e78f4deb681f3128c3e75dbd1/sites",
        "params": {"pageSize": 10, "page": 1}
      },
      {
        "method": "GET",
        "url": "/openapi/v1/de382a0e78f4deb681f3128c3e75dbd1/devices",
        "params": {"siteId": "640effd1b3f2ae5b912275ec"}
      }
    ]
  }' \
  -X POST -k
```

--------------------------------

### Omada API Obtain Authorization Code Request (cURL)

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

This cURL command illustrates how to obtain an authorization code from the Omada Open API after a successful login. It requires the client ID, Omada ID, response type, CSRF token, and session ID. The authorization code is valid for 2 minutes.

```bash
curl "https://localhost:8043/openapi/authorize/code?client_id=29f2fdbeb5a84d50b9b1cdd08cd1a3ff&omadac_id=de382a0e78f4deb681f3128c3e75dbd1&response_type=code" -H 'content-type:application/json' -H 'Csrf-Token:ae6b935c92cf4b1b9f3eb852e20ed2b8' -H 'Cookie:TPOMADA_SESSIONID=9cb86bf3a99e48a59e4f3bb464a3c443' -X POST -i -k --insecure
```

--------------------------------

### Regional Endpoints

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

Provides base URLs for Cloud-Based Controller (CBC) domains across different regions for both frontend OAuth login and REST API access.

```APIDOC
## Regional Endpoints

### Cloud-Based Controller (CBC) Domain Names

**Frontend OAuth Login URLs:**
*   **Singapore:** `https://aps1-omada-controller.tplinkcloud.com`
*   **Europe:** `https://euw1-omada-controller.tplinkcloud.com`
*   **US:** `https://use1-omada-controller.tplinkcloud.com`

**REST API Base URLs:**
*(Note: The specific REST API base URLs are typically derived from the region, e.g., `https://use1-omada-northbound.tplinkcloud.com` for the US region. Always append the specific API endpoints to these base URLs.)*
```

--------------------------------

### Batch Processing OpenAPIs

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html/index

Processes up to 20 other OpenAPIs, excluding MSP OpenAPIs. All processing should use the same omadacId.

```APIDOC
## Batch Processing OpenAPIs

### Description
Allows processing up to 20 other OpenAPIs through a single request, excluding MSP OpenAPIs. Requires the same `omadacId` for all operations.

In MSP mode, this endpoint can process up to 20 other OpenAPIs through the OpenAPI **Batch Processing MSP OpenAPIs**. For dealing with MSP OpenAPIs, the same `mspId` should be used. For dealing with other non-MSP OpenAPIs, the corresponding `customerId` should be used.

### Method
POST (Assumed, as batch operations typically use POST)

### Endpoint
/batch

### Parameters
(Specific parameters for batch processing are not detailed in the provided text, but would typically include a list of operations and their parameters.)

### Request Example
(Example not provided in the source text.)

### Response
(Response structure not detailed in the source text.)
```

--------------------------------

### MSP-Level Audit Log Categories

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

Lists the categories for audit logs at the MSP (Managed Service Provider) level. These categories cover administrative actions related to account management, backups, cloud access, device management, licensing, system settings, and more. Each category is represented by a short, descriptive key.

```text
ACCOUNT           - User account operations
BACKUP            - Backup operations
CLOUD_ACCESS      - Cloud access events
DASHBOARD         - Dashboard activities
DATA_EXPORT       - Data export operations
DEVICE_MANAGEMENT - Device management operations
LICENSE           - License management
LOG               - Log management
MSP_SETTINGS      - MSP settings changes
RESTORE           - Restore operations
SITE_MANAGEMENT   - Site management operations
SYSTEM_SETTINGS   - System configuration changes
USER_INTERFACE    - UI-related events
WEBHOOK_SETTINGS  - Webhook configuration changes
```

--------------------------------

### Batch Processing Multiple API Requests

Source: https://context7.com/context7/use1-omada-northbound_tplinkcloud_doc/llms.txt

Execute multiple API operations within a single request, up to a maximum of 20 operations. Supports both non-MSP and MSP batch operations with different URL structures.

```APIDOC
## POST /openapi/v1/batch (Non-MSP)
## POST /openapi/v1/msp/batch (MSP)

### Description
Execute multiple API operations in a single batch request. Non-MSP batches require all operations to target the same Omada controller (`omadacId`), while MSP batches support operations across different customer accounts.

### Method
POST

### Endpoint
- Non-MSP: `/openapi/v1/batch`
- MSP: `/openapi/v1/msp/batch`

### Parameters
#### Query Parameters
None

#### Request Body
- **operations** (array) - Required - An array of operation objects to be executed.
  - **method** (string) - Required - The HTTP method for the operation (e.g., 'GET', 'POST').
  - **url** (string) - Required - The endpoint path for the operation. For MSP batches, use placeholders like `{mspId}` or `{customerId}`.
  - **params** (object) - Optional - Query parameters for the operation.
  - **body** (object) - Optional - Request body for the operation (if applicable).

### Request Example (Non-MSP)
```json
{
  "operations": [
    {
      "method": "GET",
      "url": "/openapi/v1/de382a0e78f4deb681f3128c3e75dbd1/sites",
      "params": {"pageSize": 10, "page": 1}
    },
    {
      "method": "GET",
      "url": "/openapi/v1/de382a0e78f4deb681f3128c3e75dbd1/devices",
      "params": {"siteId": "640effd1b3f2ae5b912275ec"}
    }
  ]
}
```

### Request Example (MSP)
```json
{
  "operations": [
    {
      "method": "GET",
      "url": "/openapi/v1/msp/{mspId}/customers",
      "params": {"pageSize": 10}
    },
    {
      "method": "GET",
      "url": "/openapi/v1/{customerId}/sites",
      "params": {"pageSize": 10}
    }
  ]
}
```

### Response
#### Success Response (200)
Responses will vary based on the operations performed. Each operation within the batch will have its own response object, potentially including an `errorCode`, `msg`, and `result`.

**Important Notes:**
- **Limitation:** Maximum 20 operations per batch.
- **Restriction:** MSP-level APIs are excluded from non-MSP batch operations.
```