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
make all
Releasing a new version
This repository uses a two-phase release flow with
go-changesets:
changesets-version-pr reads pending .changeset/*.md files and opens/updates a release PR.
changesets-publish runs after merge to main and publishes tags/releases when version.txt is newer than the latest tag.
Add a changeset
Install tools:
go install tool
Create a changeset file interactively:
changeset add
Changeset files are committed under .changeset/ and consumed automatically by the version PR workflow.
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 generates the Go client SDK from the fixed spec
- Patch specs from
generator/patches/ are merged into the fixed upstream spec (including auth endpoints)
- 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;
mkdocs-exclude
mkdocs-awesome-nav
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.