Authenticating with OAuth2
Learn how to link an OAuth2 application with your account, then use it to act on behalf of your users.
So you want to integrate your app with Wistia. Cool! To make it really easy for your end-users to connect their Wistia account, you’ll want to use the OAuth2 protocol.
Here you’ll find an overview of our OAuth flow and the technical details you need to implement it.
What is OAuth2?
This page is meant for people who have a grasp of how OAuth2 works. If you’re not sure, check out the official OAuth2 resource.
Get Approved
OAuth2 is not yet available for all accounts. Until it is, contact us to get it enabled.
Create an OAuth Application
Before you can perform the OAuth protocol, you need to register an oauth application with us. By doing this, your users will be able to verify that your app is genuine, and that they authorize whatever permissions you request.
- Go to Account > Settings.
- Click the Oauth Applications tab in the sidebar.
- Click on New Application.
- Enter a name, a brief description, a Redirect URI (also known as a Callback URL in some circles), and Permissions for your app. These can be changed later, so don’t fret too much over them. Click Save.
- Your app should now be visible in the list of OAuth Applications.
- Click the name of your app, or Edit, to get credentials and update your app’s information.
Notes on Permissions
You can choose multiple permissions — also known as “scopes” — when you create or edit your OAuth Application. The permissions you choose there will be the same permissions as those that the end user must approve when they grant your application authorization.
Changing Application permissions will not update the permissions for already existing access tokens. The end-user will need to revalidate if those permissions change.
Available Scopes
If you think you have a use case that is not covered by one or a combination of these scopes, contact us and explain your situation to us. Maybe we can help you out!
all:all
Anything you can do with our API is allowed.
all:read
All requests for data are allowed, but no changes can be made.
media:read
All requests for media and project data are allowed. This also extends to customization and captions data.
stats:read
All requests for stats data are allowed.
media:upload
Uploading via the API is allowed, as well as fetching data about a single media by hashed ID (i.e. medias#show).
Perform an API request with OAuth credentials
There are three ways to authenticate with your token.
- Include it in the
access_token
query param. - Include it in the
bearer_token
query param. - Include it in the “Authorization” request header as
Bearer %s
, where%s
is the token.
The Upload API will only support the first two methods. That is, via the access_token
or bearer_token
in a query param.
Use the Refresh Token to renew your Access Token
With every access token response, we also return a “refresh token.” You can trade a refresh token for another access token. By using a refresh token, you can get an API key for a user without requiring re-authorization.
base_url = 'https://api.wistia.com'
client_id = '5e7580f112852db6708eac9ce77f6592ffb95a3443e2f038de2ed5a82d7ca8d1'
client_secret = 'f4fa3d09f45c5c5be6e1f9f0a336e24493f9cff9ed310442f4b5270c34be6fc2'
client = OAuth2::Client.new(client_id, client_secret, site: base_url)
# Trade the refresh_token for a new access_token
old_access_token = OAuth2::AccessToken.new(client, refresh_token: 'thesavedrefreshtoken')
token = old_access_token.refresh!
# Your refresh_token will stay the same until the end-user goes through the
# OAuth flow again.
token.refresh_token
Note: These keys are not valid and are for demonstration purposes only.
Technical Reference
Site URL
This is just the base URL of the Wistia API. It can be used as the base URL for the other endpoints.
Authorize URL
https://api.wistia.com/oauth/authorize
Expects a request like:
https://api.wistia.com/oauth/authorize?client_id=mypublicconsumerkey&redirect_uri=https%3A%2F%2Flocalhost%2Fmyapp&response_type=code
It will ultimately redirect back to the Redirect URI with a code
param if
succesful, or error
and error_description
params if unsuccessful.
Token URL
https://api.wistia.com/oauth/token
It expects requests like:
POST https://api.wistia.com/oauth/token?client_id=myclientid&client_secret=myclientsecret&grant_type=authorization_code&code=myauthorizationcode&redirect_uri=https%3A%2F%2Flocalhost%2Fmyapp
POST https://api.wistia.com/oauth/token?client_id=myclientid&client_secret=myclientsecret&grant_type=refresh_token&refresh_token=myrefreshtoken
Responds with JSON in the form:
{
"access_token": "ba371cc8c511e0d9114b8e17777ebc4ad5e23811144341f0ca4726d67ff4b19e",
"token_type": "bearer",
"expires_in": 21600,
"refresh_token": "366d1b695bccf10bae1b50bb869ea17187328e5b90045eb6368d7c912f03393c",
"scope": ["all:read"]
}
Revoking Access
A user can revoke access to your app by going to Account > My Settings.
Known Issues
- The wistia-api ruby gem currently does not support oauth. We will be updating this in the future.
- Only Managers and owners of an account can authorize an application at this time.