README
¶
Go Trakt Device Auth Library
A Go library to allow an end user to authorize a third-party Trakt application access to their account using the device method.
Conventions
Client ID and Client Secret
Throughout the library, the Client ID and Client Secret are used to tell Trakt which app is requesting access. These values are found in the dashboard for the app on Trakt's website, as shown in the image below.
Context Functions
Many functions in this library have context counterparts which allow a custom context.Context to be used. If you don't know what all this means, you'll probably be fine sticking with the non-context versions.
Installation
As a Go library: go get -u github.com/BrenekH/go-traktdeviceauth
As an executable: go install github.com/BrenekH/go-traktdeviceauth/cmd@latest
or download from the latest release.
Usage
As suggested by the official API docs, a device and user code pair must be generated as the first step using GenerateNewCode. Next, the user needs to directed to the returned verification url and instructed to enter the user code into the website. Finally, PollForAuthToken is used to wait for the user to complete authentication or the code to expire.
If the returned access token expires, a new one can be generated with asking the user to re-authenticate by using RefreshAccessToken
Trakt recommends that the AccessToken and RefreshToken be saved in permanent storage so that the user doesn't need to log in every time your program starts.
License
This project is licensed under the Apache 2.0 license, a copy of which can be found in LICENSE.
Documentation
¶
Index ¶
- Variables
- type CodeResponse
- type TokenResponse
- func PollForAuthToken(codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)
- func PollForAuthTokenContext(ctx context.Context, codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)
- func RefreshAccessToken(refreshToken, clientID, clientSecret string) (TokenResponse, error)
- func RefreshAccessTokenContext(ctx context.Context, refreshToken, clientID, clientSecret string) (TokenResponse, error)
- func RequestToken(codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)
- func RequestTokenContext(ctx context.Context, codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)
Constants ¶
This section is empty.
Variables ¶
var ( ErrDeviceCodeUnclaimed error = errors.New("the user has not yet claimed the device code") // 400 ErrInvalidGrant error = errors.New(invalidGrantText) // 401 ErrInvalidDeviceCode error = errors.New("invalid device code") // 404 ErrForbidden error = errors.New("invalid API key or unapproved application") // 403 ErrDeviceCodeAlreadyApproved error = errors.New("device code has already been approved") // 409 ErrDeviceCodeExpired error = errors.New("the device code has expired, please regenerate a new one") // 410 ErrDeviceCodeDenied error = errors.New("the device code was denied by the user") // 418 ErrPollRateTooFast error = errors.New("the API is being polled too quickly") // 429 ErrServerError error = errors.New("the Trakt API is reporting an internal problem, please check back later") // 500 ErrServiceOverloaded error = errors.New("the servers are overloaded, please try again in 30 seconds") // 503, 504 ErrCloudflareError error = errors.New("there is an issue with Cloudflare") // 520, 521, 522 )
var TraktAPIBaseUrl string = "https://api.trakt.tv"
TraktAPIBaseUrl is the base url for all API requests. This shouldn't need to be modified unless targetting a different server, for instance the staging server (https://api-staging.trakt.tv)
Functions ¶
This section is empty.
Types ¶
type CodeResponse ¶
type CodeResponse struct {
DeviceCode string `json:"device_code"`
UserCode string `json:"user_code"`
VerificationURL string `json:"verification_url"`
ExpiresIn int `json:"expires_in"` // How long the code will last in seconds
Interval int `json:"interval"` // The interval in seconds that the application is allowed to poll at
}
CodeResponse is used to contain the results of GenerateNewCode. The user should be directed to VerificationURL and instructed to enter UserCode into the box presented. None of this data needs to persist between restarts.
func GenerateNewCode ¶
func GenerateNewCode(clientID string) (CodeResponse, error)
GenerateNewCode wraps GenerateNewCodeContext using context.Background().
func GenerateNewCodeContext ¶
func GenerateNewCodeContext(ctx context.Context, clientID string) (CodeResponse, error)
GenerateNewCodeContext reaches out to the Trakt API to acquire a claimable code.
type TokenResponse ¶
type TokenResponse struct {
AccessToken string
TokenType string
ExpiresAt time.Time
RefreshToken string
Scope string
CreatedAt time.Time
}
TokenResponse contains the results of RequestToken. This data should persist between restarts unless you want to prompt the user to authorize your app on every launch.
func PollForAuthToken ¶
func PollForAuthToken(codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)
PollForAuthToken wraps PollForAuthTokenContext using context.Background().
func PollForAuthTokenContext ¶
func PollForAuthTokenContext(ctx context.Context, codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)
PollForAuthTokenContext continuously polls for the access token from a CodeResponse. The passed context is truncated using context.WithDeadline to match the CodeResponse.ExpiresIn value.
func RefreshAccessToken ¶
func RefreshAccessToken(refreshToken, clientID, clientSecret string) (TokenResponse, error)
RefreshAccessToken wraps RefreshAccessTokenContext with a context.Background() struct. Please refer to RefreshAccessTokenContext for documentation.
func RefreshAccessTokenContext ¶
func RefreshAccessTokenContext(ctx context.Context, refreshToken, clientID, clientSecret string) (TokenResponse, error)
RefreshAccessTokenContext takes the refresh token from a previous TokenResponse and creates a new one. This should only be used when an AccessToken expires (after about 3 months according to Trakt).
func RequestToken ¶
func RequestToken(codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)
RequestToken wraps RequestTokenContext using context.Background().
func RequestTokenContext ¶
func RequestTokenContext(ctx context.Context, codeResp CodeResponse, clientID, clientSecret string) (TokenResponse, error)
RequestTokenContext determines returns a TokenResponse if the provided code has been claimed by the user. If it has not, or there is another error, it will RequestTokenContext returns a customized error value which details the issue.
This function is provided as a convenience, but it is recommended to use PollForAuthToken unless you have a very specific use case for this function.
Source Files
Directories