OAuth 2 Code Authorization Flow

This guide describes the basics of executing the OAuth 2 code flow to generate Frame.io tokens.


Frame.io supports the creation and management of OAuth 2 applications. Unlike Developer Tokens, OAuth 2 apps enable any Frame.io user to grant his or her credentials via secure login, after which the app may act on that user's behalf.

In plain terms, OAuth 2 apps are best for any integration scenario in which an individual user's context and access are important.

OAuth 2 Code Flow

The basic sequence

At a very high level, OAuth 2 has three parties:

  1. The User (in our case: anyone with a Frame.io login)
  2. The client Application (the external OAuth2.0 app)
  3. The credentials Server (in our case: Frame.io)

Code flow for OAuth 2 is a four-step process through which:

  1. The Application presents the User with a login screen
  2. The User enters his or her credentials, which go directly to the Server
  3. If the login is successful, the Server sends back a page asking the User to confirm that he or she would like to grant a preconfigured set of access scopes to the Application
  4. If the User consents, the Server sends the Application a token that can be used to act on behalf of the User with the requested scopes.

In this way, an client application can take action on the user's behalf, securely, with the user's permission, and (importantly) without ever seeing or handling the user's actual credentials.

The callback cycle

The above sequence relies on the server (Frame.io) hosting two services, each with its own route:

Authhttps://applications.frame.io/oauth2/authGETGiven information about the OAuth client application, invokes the auth flow with the server.
Tokenhttps://applications.frame.io/oauth2/tokenPOSTGiven information from the auth step, retrieves a token on the user's behalf.

The OAuth 2 application's role in this cycle is to identify itself to the server, and make those two requests.

Quick example

[[info | Have you built an OAuth 2 app before?]] | If you're familiar with the rest of the plumbing for OAuth2.0, the below example may be enough for you to get started. If you'd like a bit more detail, check out the more detailed guide here.

Setting up your App

  1. Sign into the Frame.io Developer Portal using your Frame.io credentials, navigate to OAuth Apps using the links on the left-hand side, and click New to start setting up your app.
  2. On the subsequent screen, enter a Name and Redirect URI for your app, select your Scopes, and choose whether to use PKCE.
  3. Save, and you should now see your new app configuration.

[[info | About PKCE]] | The Proof Key for Code Exchange setting will enable your app to request tokens without providing its client_secret. As such, you will not be provided with a client_secret, and should not include an Authorization header when POSTing for a token in your app's callback cycle. That said, you will need to include your client_id in your callback, or else your request will be denied.

Our advice is to use the normal code flow (without PKCE) whenever possible.

Building your OAuth 2 Application

Now that you have an app configuration in Frame.io, you can go about setting up your callback server to handle the two key routes to complete the callback cycle, per the table above.

For more detailed information on how to build out your application, please refer to Building an OAuth 2 App.