authorization

Documentation

Overview

Package authorization handles allowing us to generate an access token to perform actions on behalf of an authenticated user.

Authorization - OAuth.

The API uses OAuth2. If you know what's up with OAuth2, grab your library and starting rolling. If you have access to a web browser (mobile app, desktop app, website), use standard OAuth. If you don't have web browser access (media center plugins, smart watches, smart TVs, command line scripts, system services), use Device authentication.

Application Flow:

1. Redirect to request Trakt access. Using the /oauth/authorize method, construct then redirect to this URL. The Trakt website will request permissions for your app and the user will have the opportunity to sign up for a new Trakt account or sign in with their existing account.

2. Trakt redirects back to your site. If the user accepts your request, Trakt redirects back to your site with a temporary code in a code GET parameter as well as the state (if provided) in the previous step in a state parameter. If the states don’t match, the request has been created by a third party and the process should be aborted.

3. Exchange the code for an access token. If everything looks good in step 2, exchange the code for an access token using the /oauth/token method. Save the access_token so your app can authenticate the user by sending the Authorization header as indicated below or in any example code. The access_token is valid for 3 months. Save and use the refresh_token to get a new access_token without asking the user to re-authenticate.

Authorization - Device.

Device authentication is for apps and services with limited input or display capabilities. This include media center plugins, smart watches, smart TVs, command line scripts, and system services. Your app displays an alphanumeric code (typically 8 characters) to the user. They are then instructed to visit the verification URL on their computer or mobile device. After entering the code, the user will be prompted to grant permission for your app. After your app gets permissions, the device receives an access_token and works like standard OAuth from that point on.

Application Flow:

1. Generate codes. Your app calls /oauth/device/code to generate new codes. Save this entire response for later use.Display the code. Display the user_code and instruct the user to visit the verification_url on their computer or mobile device.Poll for authorization.

2. Poll the /oauth/device/token method to see if the user successfully authorizes your app. Use the device_code and poll at the interval (in seconds) to check if the user has authorized your app. Check the docs below for the specific error codes you need to handle. Use expires_in to stop polling after that many seconds, and gracefully instruct the user to restart the process. It is important to poll at the correct interval and also stop polling when expired.

3. Successful authorization. When you receive a 200 success response, save the access_token so your app can authenticate the user in methods that require it. The access_token is valid for 3 months. Save and use the refresh_token to get a new access_token without asking the user to re-authenticate. It's normal OAuth from this point.

Index

• func AuthorizeURL(params *trakt.AuthorizationURLParams) (string, error)
• func ExchangeCode(params *trakt.ExchangeCodeParams) (*trakt.Token, error)
• func NewCode(params *trakt.BasicParams) (*trakt.DeviceCode, error)
• func Poll(params *trakt.PollCodeParams) (*trakt.Token, error)
• func PollAsync(params *trakt.PollCodeParams) <-chan *trakt.PollResult
• func RefreshToken(params *trakt.RefreshTokenParams) (*trakt.Token, error)
• func RevokeToken(params *trakt.RevokeTokenParams) error

Functions

func AuthorizeURL

func AuthorizeURL(params *trakt.AuthorizationURLParams) (string, error)

AuthorizeURL constructs the authorization URL to redirect to. The Trakt website will request permissions for your app and the user will have the opportunity to sign up for a new Trakt account or sign in with their existing account.

Redirect URI is required, this is the URI which Trakt will redirect to after the authorization flow is complete. You can use "urn:ietf:wg:oauth:2.0:oob" for device authentication. The state is a random unique string which will be returned to the Redirect URI. This can be compared against to reduce the risk of "Man-In-The-Middle" attacks. See: https://en.wikipedia.org/wiki/Man-in-the-middle_attack

func ExchangeCode

func ExchangeCode(params *trakt.ExchangeCodeParams) (*trakt.Token, error)

ExchangeCode takes the authorization code parameter sent back to your redirect_uri to get an access_token. Save the access_token so your app can authenticate the user by sending the Authorization header. The access_token is valid for 3 months. Save and use the refresh_token to get a new access_token without asking the user to re-authenticate. This function requires the same RedirectURI which was sent in the initial request to get the code and also the client Secret which is also assigned to you when you create an application on Trakt.

func NewCode

func NewCode(params *trakt.BasicParams) (*trakt.DeviceCode, error)

NewCode Generates new codes to start the device authentication process. The device_code and interval will be used later to poll for the access_token. The user_code and verification_url should be presented to the user as mentioned in the flow steps above.

func Poll

func Poll(params *trakt.PollCodeParams) (*trakt.Token, error)

Poll uses the device_code to poll at the interval (in seconds) to check if the user has authorized you app. Use expires_in to stop polling after that many seconds, and gracefully instruct the user to restart the process. It is important to poll at the correct interval and also stop polling when expired. When you receive a 200 success response, save the access_token so your app can authenticate the user in methods that require it. The access_token is valid for 3 months. Save and use the refresh_token to get a new access_token without asking the user to re-authenticate. The interval and expires_in fields are supplied from the DeviceCode retrieved when generating a new code.

this function is blocking until either:

• we receive a 200 response with access token from the API.
• the supplied context is marked as done
• the supplied expires in duration exceeds its deadline
• any errors which deem that the token cannot be processed are returned from the API.

if you require more control over when your app blocks for the result, use PollAsync which returns a channel that the result is pushed to.

func PollAsync

func PollAsync(params *trakt.PollCodeParams) <-chan *trakt.PollResult

Poll uses the device_code to poll at the interval (in seconds) to check if the user has authorized you app. Use expires_in to stop polling after that many seconds, and gracefully instruct the user to restart the process. It is important to poll at the correct interval and also stop polling when expired. When you receive a 200 success response, save the access_token so your app can authenticate the user in methods that require it. The access_token is valid for 3 months. Save and use the refresh_token to get a new access_token without asking the user to re-authenticate. The interval and expires_in fields are supplied from the DeviceCode retrieved when generating a new code.

This function does not block but instead returns a read-only channel which will have the result of polling for the result once it is available.

func RefreshToken

func RefreshToken(params *trakt.RefreshTokenParams) (*trakt.Token, error)

RefreshToken uses the Refresh Token to get a new Access Token without asking the user to re-authenticate. The Access Token is valid for 3 months before it needs to be refreshed again. This function requires the same RedirectURI which was sent in the initial request to get the code and also the client Secret which is also assigned to you when you create an application on Trakt.

func RevokeToken

func RevokeToken(params *trakt.RevokeTokenParams) error

RevokeToken revokes an access token when a user signs out of their Trakt account in your app. This is not required, but might improve the user experience so the user doesn't have an unused app connection hanging around. This function requires the client Secret which is also assigned to you when you create an application on Trakt.