OAuth 2.0 Code Authorization Flow

This guide describes the basics of executing the OAuth2.0 code flow to generate Frame.io tokens.


Overview

Frame.io supports the creation and management of OAuth2.0 applications. Unlike Developer Tokens, OAuth2.0 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, OAuth2.0 apps are best for any integration scenario in which an individual user's context and access are important.

OAuth2.0 Code Flow

The basic sequence

At a very high level, OAuth2.0 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 OAuth2.0 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:

ServiceURLMethodDescription
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 OAuth2.0 application's role in this cycle is to identify itself to the server, and make those two requests.

Quick example

Have you built an OAuth2.0 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: Building an OAuth2.0 App

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.
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 OAuth2.0 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 OAuth2.0 App