TP-LINK OMADA OPENAPI BUG REPORT

 

REPORTER INFORMATION

Date: February 8, 2026

Hardware: OC300 v1.0

Firmware: 1.32.10 Build 20260117 Rel.84796 (Stable)

Controller Version: Omada SDN 6.1.0.19

 

SUMMARY

OpenAPI v1 Client Credentials mode authentication succeeds, but all subsequent API calls to the /openapi/v1/sites endpoint fail with error code -7131 "Controller ID not exist." This makes the OpenAPI feature unusable for programmatic access to the controller.

 

DETAILED DESCRIPTION

When attempting to use the Omada OpenAPI v1 with Client Credentials mode (OAuth), the authentication process works correctly and returns a valid access token. However, any attempt to access the sites endpoint fails with the error "Controller ID not exist" (errorCode: -7131).

 

This issue persists across:

• Multiple OpenAPI applications (tested with different roles: Admin and Super Admin)
• Different endpoint URL formats
• Different methods of passing the omadacId (path, query parameter, header)
• Both Web API v2 username/password authentication and OpenAPI v1 OAuth authentication

 

STEPS TO REPRODUCE

1. Create OpenAPI application in Controller Settings → Platform Integration → Open API

• Mode: Client Credentials
• Role: Super Admin (also tested with Admin)
• Site Privileges: All sites selected

 

2. Obtain OAuth access token (THIS WORKS):

POST https://192.168.0.100:443/openapi/authorize/token?grant_type=client_credentials

Body: {"omadacId": "<OMADAC_ID>", "client_id": "<CLIENT_ID>", "client_secret": "<CLIENT_SECRET>"}

 

Response: SUCCESS

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

 

3. Attempt to get sites list (THIS FAILS):

Tried multiple endpoint formats:

 

a) With omadacId in path:

GET https://192.168.0.100:8043/openapi/v1/<OMADAC_ID>/sites

Header: Authorization: AccessToken=AT-...

Response: HTTP 500 Internal Server Error

 

b) With omadacId as query parameter:

GET https://192.168.0.100:8043/openapi/v1/sites?omadacId=<OMADAC_ID>

Header: Authorization: AccessToken=AT-...

Response: HTTP 200

{"msg": "Controller ID not exist.", "errorCode": -7131}

 

c) With omadacId as custom header:

GET https://192.168.0.100:8043/openapi/v1/sites

Headers: Authorization: AccessToken=AT-...  |  Omadac-Id: <OMADAC_ID>

Response: HTTP 200

{"msg": "Controller ID not exist.", "errorCode": -7131}

 

EXPECTED BEHAVIOR

The /openapi/v1/sites endpoint should return a list of sites managed by the controller:

{"errorCode": 0, "msg": "Success.", "result": {"data": [{"siteId": "...", "name": "...", ...}]}}

 

ACTUAL BEHAVIOR

All attempts to access the sites endpoint result in either:

• HTTP 500 Internal Server Error (when omadacId is in the URL path), OR
• HTTP 200 with error: {"msg": "Controller ID not exist.", "errorCode": -7131}

 

ADDITIONAL TESTING

We also tested Web API v2 with username/password authentication:

 

4. Get controller info (WORKS):

GET https://192.168.0.100:8043/api/info

Response: SUCCESS - returns omadacId

 

5. Login with username/password (FAILS):

POST https://192.168.0.100:8043/<OMADAC_ID>/api/v2/login

Body: {"username": "admin", "password": "<PASSWORD>"}

Response: HTTP 500 Internal Server Error

 

This suggests the issue affects both OpenAPI v1 and Web API v2.

 

ENVIRONMENT DETAILS

• Controller Type: Hardware Controller (OC300 v1.0)
• Firmware Version: 1.32.10 Build 20260117 Rel.84796 (Stable)
• Controller Software: Omada SDN 6.1.0.19
• Network Configuration: Local network access (192.168.0.100)
• OpenAPI Application Settings:

     • Mode: Client Credentials

     • Role: Super Admin

     • Site Privileges: All sites enabled

• OAuth Ports: 443 (OAuth), 8043 (API calls)
• Tested with: Python 3.9 using requests library

 

RESEARCH FINDINGS

Similar issues reported by other users:

6. TP-Link Community Forum post (topic 829674) - User reported identical -7131 error
7. GitHub issues on docker-omada-controller (#263, #344) - Similar "Controller ID not exist" errors reported
8. Most working OpenAPI examples found online are using:

     • Authorization Code mode (not Client Credentials)

     • Older controller versions (5.x series)

     • Software controllers (not hardware like OC300)

 

IMPACT

• OpenAPI feature is completely non-functional for programmatic access
• Cannot automate network management tasks
• Cannot integrate with third-party monitoring/automation platforms
• Significantly reduces value of the OpenAPI feature

 

WORKAROUND

None available. Manual web interface access is the only option.

 

SUGGESTED FIX

Investigation needed into:

9. Why Client Credentials mode fails to properly associate the controller ID with API requests after successful authentication
10. Why the 500 Internal Server Error occurs when omadacId is in the URL path
11. Whether OpenAPI is fully supported/tested on hardware controllers (OC200/OC300)
12. Whether this is a regression introduced in version 6.1.0.19

 

SUPPORTING DOCUMENTATION

Full debug logs and Python scripts used for testing available upon request.

 

REQUEST

Please investigate this issue and provide:

13. Confirmation that OpenAPI Client Credentials mode should work on OC300 hardware
14. Correct endpoint format and authentication method for accessing sites
15. Timeline for a fix if this is a confirmed bug
16. Workaround if available while waiting for a fix

 

Thank you for your attention to this matter.