Agora Go Token Builder

go-tokenbuilder generates server-side authentication tokens for Agora services. It supports the current AccessToken2 (Token007) format as well as the repository's legacy token packages.

Install the latest release:

go get github.com/AgoraIO-Community/go-tokenbuilder@v1.5.0

The module declares Go 1.14 compatibility.

Generate tokens on a trusted server. Never embed or expose your Agora App Certificate in browser, mobile, desktop, or other client-side code.

Use short expiration periods and require the channel name and user identity in the token to match the values used by the Agora client.

ConvoAI and STT tokens contain RTC and RTM services plus their respective product service. The ConvoAI and STT services have no privilege payload; their presence in the signed token grants access to that service.

The accesstoken2 package supports multiple services of the same type through AddService and GetServices. Its public Services map remains available in v1 as a backward-compatible view of the last service for each type.

package main

import (
	"log"
	"os"

	"github.com/AgoraIO-Community/go-tokenbuilder/convoaitokenbuilder"
	"github.com/AgoraIO-Community/go-tokenbuilder/rtctokenbuilder2"
)

func main() {
	const expire = uint32(3600)

	token, err := convoaitokenbuilder.BuildTokenWithConfig(convoaitokenbuilder.Config{
		AppID:                            os.Getenv("AGORA_APP_ID"),
		AppCertificate:                   os.Getenv("AGORA_APP_CERTIFICATE"),
		ChannelName:                      "my-channel",
		RTCAccount:                       "rtc-user",
		RTCRole:                          rtctokenbuilder2.RolePublisher,
		RTCTokenExpire:                   expire,
		JoinChannelPrivilegeExpire:       expire,
		PublishAudioPrivilegeExpire:      expire,
		PublishVideoPrivilegeExpire:      expire,
		PublishDataStreamPrivilegeExpire: expire,
		RTMUserID:                        "rtm-user",
		RTMTokenExpire:                   expire,
	})
	if err != nil {
		log.Fatal(err)
	}

	log.Print(token)
}

STT uses the same validated configuration and expiration model:

token, err := stttokenbuilder.BuildTokenWithConfig(stttokenbuilder.Config{
	AppID:                            appID,
	AppCertificate:                   appCertificate,
	ChannelName:                      channelName,
	RTCAccount:                       rtcAccount,
	RTCRole:                          rtctokenbuilder2.RolePublisher,
	RTCTokenExpire:                   rtcTokenExpire,
	JoinChannelPrivilegeExpire:       joinChannelPrivilegeExpire,
	PublishAudioPrivilegeExpire:      pubAudioPrivilegeExpire,
	PublishVideoPrivilegeExpire:      pubVideoPrivilegeExpire,
	PublishDataStreamPrivilegeExpire: pubDataStreamPrivilegeExpire,
	RTMUserID:                        rtmUserID,
	RTMTokenExpire:                   rtmTokenExpire,
})

The config builders validate identifier lengths, credentials, roles, and expiration relationships before building. The positional BuildToken functions remain available for compatibility.

See the complete runnable ConvoAI and STT examples.

• rtctokenbuilder2 generates RTC AccessToken2 tokens for numeric UIDs or user accounts, with either shared or individual privilege expirations.
• rtmtokenbuilder2 generates RTM AccessToken2 tokens.
• rtmtokenbuilder2.BuildTokenWithPermissions generates service type 8 RTM tokens with resource-level permissions; coordinate with Agora before using this specialized interface.
• rtctokenbuilder2.BuildTokenWithRtm and BuildTokenWithRtm2 generate combined RTC and RTM tokens.
• Legacy packages remain available for backward compatibility.

For new integrations, prefer the packages ending in 2 and the ConvoAI or STT builders introduced in v1.5.0.

Parse decodes a token but does not establish that it is authentic. Call VerifySignature with the App Certificate after parsing when accepting a token from an untrusted source:

parsed := accesstoken2.CreateAccessToken()
if ok, err := parsed.Parse(token); err != nil || !ok {
	return err
}
valid, err := parsed.VerifySignature(appCertificate)

Malformed tokens return errors and clear previously parsed signature state.

Run all checks from the repository root:

go fmt ./...
go vet ./...
go test ./...

CI measures production-package coverage separately from runnable examples and the internal test assertion helper:

go list ./... \
  | grep -Ev '/examples/|/internal/testutil$' \
  | xargs go test -coverprofile=coverage.out
go tool cover -func=coverage.out

The enforced production coverage floor is 95%.

See CHANGELOG.md for release notes. Releases follow semantic versioning and are published as Git tags such as v1.5.0.

Breaking naming and API normalization is intentionally deferred to the next major release; see V2_MIGRATION.md.

This project is licensed under the MIT License. See LICENSE.