or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

accounts.mdauthentication.mdconversations.mdfilters.mdindex.mdinstance.mdlists.mdmedia.mdnotifications.mdpolls.mdreports.mdsearch.mdstatuses.mdstreaming.mdtags.mdtimelines.mdtypes.md
tile.json

authentication.mddocs/

Authentication

go-mastodon supports multiple authentication methods to access the Mastodon API: application credentials for bot/service access, user credentials for individual user access, and OAuth for user-authorized applications.

Application Registration

Before authenticating, you must register your application with a Mastodon instance.

RegisterApp

func RegisterApp(ctx context.Context, appConfig *AppConfig) (*Application, error)

Registers a new application with a Mastodon instance and returns application credentials.

Parameters:

  • ctx: Context for cancellation and timeouts
  • appConfig: Application configuration including server, name, redirect URIs, and scopes

Returns:

  • *Application: Application credentials including ClientID, ClientSecret, and AuthURI
  • error: Error if registration fails

Example:

app, err := mastodon.RegisterApp(context.Background(), &mastodon.AppConfig{
    Server:       "https://mastodon.social",
    ClientName:   "My Mastodon App",
    RedirectURIs: "urn:ietf:wg:oauth:2.0:oob",
    Scopes:       "read write follow",
    Website:      "https://example.com",
})
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Client ID: %s\n", app.ClientID)
fmt.Printf("Client Secret: %s\n", app.ClientSecret)
fmt.Printf("Auth URI: %s\n", app.AuthURI)

Authentication Methods

Application Access Token

Use application credentials to access public data without user authorization.

func (c *Client) GetAppAccessToken(ctx context.Context, redirectURI string) error

Exchanges API credentials for an application access token. This token provides limited access to public data only.

Parameters:

  • ctx: Context for cancellation and timeouts
  • redirectURI: Must match the redirect URI used during application registration

Returns:

  • error: Error if token exchange fails

Example:

config := &mastodon.Config{
    Server:       "https://mastodon.social",
    ClientID:     app.ClientID,
    ClientSecret: app.ClientSecret,
}
client := mastodon.NewClient(config)

err := client.GetAppAccessToken(context.Background(), "urn:ietf:wg:oauth:2.0:oob")
if err != nil {
    log.Fatal(err)
}

// Client now has access token for public data
instance, err := client.GetInstance(context.Background())

User Access Token (OAuth)

Use OAuth flow to obtain user authorization and access token.

func (c *Client) GetUserAccessToken(ctx context.Context, authCode string, redirectURI string) error

Exchanges a user authorization code for a user access token. The authorization code is obtained by directing the user to the AuthURI provided by RegisterApp.

Parameters:

  • ctx: Context for cancellation and timeouts
  • authCode: Authorization code obtained from user authorization
  • redirectURI: Must match the redirect URI used during application registration

Returns:

  • error: Error if token exchange fails

Example:

// 1. Register application and get AuthURI
app, err := mastodon.RegisterApp(context.Background(), &mastodon.AppConfig{
    Server:       "https://mastodon.social",
    ClientName:   "My Mastodon App",
    RedirectURIs: "urn:ietf:wg:oauth:2.0:oob",
    Scopes:       "read write follow",
})

// 2. Direct user to app.AuthURI to authorize
fmt.Printf("Please visit: %s\n", app.AuthURI)
fmt.Print("Enter authorization code: ")
var authCode string
fmt.Scanln(&authCode)

// 3. Exchange authorization code for access token
config := &mastodon.Config{
    Server:       "https://mastodon.social",
    ClientID:     app.ClientID,
    ClientSecret: app.ClientSecret,
}
client := mastodon.NewClient(config)

err = client.GetUserAccessToken(context.Background(), authCode, "urn:ietf:wg:oauth:2.0:oob")
if err != nil {
    log.Fatal(err)
}

// Client now has full user access
account, err := client.GetAccountCurrentUser(context.Background())

Direct Token Configuration

If you already have an access token, configure the client directly.

Example:

config := &mastodon.Config{
    Server:      "https://mastodon.social",
    AccessToken: "your-existing-access-token",
}
client := mastodon.NewClient(config)

// Client is ready to use
account, err := client.GetAccountCurrentUser(context.Background())

Application Verification

VerifyAppCredentials

func (c *Client) VerifyAppCredentials(ctx context.Context) (*ApplicationVerification, error)

Verifies the application credentials and returns application information.

Parameters:

  • ctx: Context for cancellation and timeouts

Returns:

  • *ApplicationVerification: Application verification data including name, website, and VAPID key
  • error: Error if verification fails

Example:

verification, err := client.VerifyAppCredentials(context.Background())
if err != nil {
    log.Fatal(err)
}
fmt.Printf("App Name: %s\n", verification.Name)
fmt.Printf("Website: %s\n", verification.Website)

Types

AppConfig

type AppConfig struct {
    http.Client
    Server       string  // Mastodon instance URL (e.g., "https://mastodon.social")
    ClientName   string  // Your application name
    RedirectURIs string  // Where user is redirected after authorization (use "urn:ietf:wg:oauth:2.0:oob" for no redirect)
    Scopes       string  // Space-separated list of scopes (e.g., "read write follow")
    Website      string  // Optional application website
}

Configuration for registering applications.

Application

type Application struct {
    ID           ID      // Application ID
    RedirectURI  string  // Redirect URI for OAuth
    ClientID     string  // Client ID for API access
    ClientSecret string  // Client secret for API access
    AuthURI      string  // URI for user authorization (not part of Mastodon API, generated by go-mastodon)
}

Application credentials returned by registration.

ApplicationVerification

type ApplicationVerification struct {
    Name     string  // Application name
    Website  string  // Application website
    VapidKey string  // VAPID key for push notifications
}

Application verification information.

Config

type Config struct {
    Server       string  // Mastodon instance URL
    ClientID     string  // Application client ID
    ClientSecret string  // Application client secret
    AccessToken  string  // User or application access token
}

Client configuration for API access.

Client

type Client struct {
    http.Client
    Config     *Config   // Client configuration
    UserAgent  string    // User agent string for HTTP requests
    JSONWriter io.Writer // Writer for JSON response logging (optional)
}

The main API client for interacting with Mastodon. All API methods are called on Client instances.

Client Initialization

NewClient

func NewClient(config *Config) *Client

Creates a new Mastodon API client with the provided configuration.

Parameters:

  • config: Client configuration including server URL and credentials

Returns:

  • *Client: New client instance ready for API calls

Example:

config := &mastodon.Config{
    Server:       "https://mastodon.social",
    ClientID:     "your-client-id",
    ClientSecret: "your-client-secret",
    AccessToken:  "your-access-token",
}
client := mastodon.NewClient(config)

Deprecated Methods

The following authentication methods are deprecated and should not be used:

  • Authenticate(ctx, username, password) - Use GetAppAccessToken() or GetUserAccessToken() instead
  • AuthenticateApp(ctx) - Use GetAppAccessToken() instead
  • AuthenticateToken(ctx, authCode, redirectURI) - Use GetUserAccessToken() instead