omada-go-sdk
Go SDK for the TP-Link Omada Open API, auto-generated from the Omada OpenAPI spec.
Note: The upstream OpenAPI spec is not fully valid. This SDK uses a spec-fixer tool to patch known issues before generation. TP-Link is working on improvements, see this forum post
Installation
go get github.com/Tohaker/omada-go-sdk
Quick Start
Client Credentials Flow
package main
import (
"context"
"fmt"
"log"
omada "github.com/Tohaker/omada-go-sdk/omada"
)
func main() {
cfg := omada.NewConfiguration()
cfg.Servers = omada.ServerConfigurations{
{URL: "https://use1-omada-northbound.tplinkcloud.com"},
}
client := omada.NewAPIClient(cfg)
// 1. Get access token via client credentials
tokenResp, _, err := client.AuthorizeAPI.AuthorizeToken(context.Background()).
GrantType("client_credentials").
TokenRequest(omada.TokenRequest{
ClientId: "your-client-id",
ClientSecret: "your-client-secret",
OmadacId: omada.PtrString("your-omadac-id"),
}).Execute()
if err != nil {
log.Fatal(err)
}
// 2. Set the access token for subsequent requests
cfg.DefaultHeader["Authorization"] = "AccessToken=" + *tokenResp.Result.AccessToken
// 3. Use API endpoints
// sites, _, err := client.SiteAPI.GetSites(context.Background(), "omadac-id").Execute()
fmt.Println("Access token obtained successfully")
}
Authorization Code Flow
// 1. Login
loginResp, _, _ := client.AuthorizeAPI.AuthorizeLogin(context.Background()).
ClientId("your-client-id").
OmadacId("your-omadac-id").
LoginRequest(omada.LoginRequest{
Username: "admin",
Password: "password",
}).Execute()
// 2. Get authorization code
codeResp, _, _ := client.AuthorizeAPI.AuthorizeCode(context.Background()).
ClientId("your-client-id").
OmadacId("your-omadac-id").
ResponseType("code").
CsrfToken(*loginResp.Result.CsrfToken).
Cookie("TPOMADA_SESSIONID=" + *loginResp.Result.SessionId).
Execute()
// 3. Exchange code for token
tokenResp, _, _ := client.AuthorizeAPI.AuthorizeToken(context.Background()).
GrantType("authorization_code").
Code(*codeResp.Result).
TokenRequest(omada.TokenRequest{
ClientId: "your-client-id",
ClientSecret: "your-client-secret",
}).Execute()
Regions
| Region |
Server URL |
| US |
https://use1-omada-northbound.tplinkcloud.com |
| EU |
https://euw1-omada-northbound.tplinkcloud.com |
| Singapore |
https://aps1-omada-northbound.tplinkcloud.com |
| Self-hosted |
Your Omada Controller URL |
Regenerating the SDK
Prerequisites: Go 1.21+, Docker.
# Run the full generation pipeline
./generator/generate.sh
Or use the GitHub Actions workflow: Actions → Generate SDK → Run workflow with a version tag (e.g. v0.1.1).
How It Works
tools/fix_spec.go fetches the upstream OpenAPI spec and fixes known issues (schema names with spaces/special chars, missing security definitions, HTTP→HTTPS)
openapi-generator-cli (pinned to v7.12.0 via Docker) generates the Go client SDK from the fixed spec
- A separate generation pass adds auth endpoints from
generator/auth-spec.yaml
- The result is a single
omada Go package in the omada/ subdirectory
Publishing docs
Docs are published using mkdocs-material.
If you've opened this repository in the devcontainer, mkdocs and all required plugins will already be installed and configured for you.
Otherwise, if you haven't done so already, follow their getting started guide to set up your local environment.
You must also install the following extra plugins;
To preview the docs locally, just run
mkdocs serve
Or build to the /site directory with
mkdocs build
Whenever docs are generated with go generate and commited to the main branch, the docs will deploy and be available to view at tohaker.github.io/omada-go-sdk.
License
See LICENSE.