How to: Authorize

Introduction

This guide demonstrates the authentication and authorization process for Camera to Cloud (C2C) devices on a Frame.io project. We’ll explore both the standard manual code entry method and the enhanced QR code pairing approach for optimal user experience.

What Will I Need?

Please review the Before We Start Implementing guide if you haven’t already.

You should have received a client_secret from our team to identify your integration. If not, please consult this introduction to the C2C ecosystem and contact our team.

Prerequisites for URL & QR Code Pairing

To implement URL & QR code pairing, ensure you meet these requirements:

• Device Compatibility: Verify your device supports URL/QR code generation during the pairing process.

Walking Through the Auth Flow

To understand the authorization flow from a user perspective, please reference these resources:

• Support Article for adding new devices.
• Training video on authorizing a Teradek Cube.

This authorization process minimizes implementation requirements. You won’t need to:

• Redirect to web browsers (unless using URL Code Pairing)
• Handle Frame.io user authentication
• Present account/project selection interfaces
• Develop complex UI components beyond basic information displays

Enhancing the User Experience with URL Code Pairing

Modern users expect efficient device interactions. While the current manual pairing process functions adequately, it can be optimized.

By implementing URL & QR code pairing—similar to streaming services like Netflix or Disney+—we can significantly streamline the process, minimize input errors, and reduce pairing time.

Device Identification (client_id)

Each physical device requires a unique identifier for connection tracking within a user’s project.

For devices, this identifier is the client_id, which is essential during authorization. When implementing, consider appropriate identifier sources such as device serial numbers, UUIDs, or other unique strings. If you are integrating on an Apple device, we recommend using a unique persistent UUID that is consistent across device reboots.

Exercise caution regarding personally identifiable information. User email addresses are not appropriate client_id values.

Additionally, ensure you control the identifier. Device MAC addresses are unsuitable as they aren’t owned by your software and may constitute personally identifiable information.

If you need guidance on selecting an appropriate identifier, our team can assist in determining a suitable value that simplifies integration.

Step 1: Requesting a Device Code

To begin implementation, request a device code through the /v2/auth/device/code endpoint:

Traditional Pairing Method

curl -X POST https://api.frame.io/v2/auth/device/code \
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

Enabling URL Code Pairing

For URL code pairing, modify the API call with additional headers:

curl -X POST https://api.frame.io/v2/auth/device/code \
    --header "x-client-version: 2.0.0" \
    --header "x-client-platypus-enabled: true" \  # New header to enable URL pairing
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

Note: These authentication endpoints accept form data exclusively, not JSON. Post-authentication, other endpoints will accept JSON payloads, but authentication endpoints will reject JSON requests.

Payload Parameters

• client_id: The unique identifier for your physical device. This must be guaranteed unique, such as a serial number or UUID.
• client_secret: Provided by Frame.io support to identify your device model. This confidential value should remain protected from users and encrypted when stored.
• scope: The requested permissions, separated by spaces. Devices may request:
  • asset_create: Enables asset creation and uploading.
  • offline: Permits authorization refreshing via refresh token. Without this scope, users would need to re-authorize their device every 8 hours as authorization tokens expire.

In practical implementations, devices typically request both scopes.

Understanding the API Response

The request generates a response similar to:

Traditional Pairing Response

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131"
}

URL Pairing Response

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131",
  "verification_uri": "https://next.frame.io/pair",
  "verification_uri_complete": "https://next.frame.io/pair/573131"
}

Response Breakdown

• device_code: This internal identifier should remain hidden from users and identifies the authorization request during polling.
• expires_in: The code’s validity period in seconds.
• interval: The recommended polling interval in seconds.
• name: The connecting device’s identifier.
• user_code: The six-digit code for manual entry into Frame.io for device pairing.
• verification_uri: The base URL for manual entry if QR scanning is unavailable.
• verification_uri_complete: The full URL containing the pairing code, intended for hyperlinking within a mobile app or QR code generation to streamline user navigation to the pairing interface.

Displaying the QR Code to the User

Using the verification_uri_complete, generate and display a QR code on the device screen for the user to scan, facilitating efficient pairing.

Example: Device Screen with QR Code Displayed

Always provide fallback options: display the user_code and verification_uri for manual entry when QR scanning isn’t possible. Alternatively, consider displaying the verification_uri as a static QR code for mobile scanning.

For mobile app integrations, include the verification_uri_complete as a tappable hyperlink since users cannot scan QR codes from the device running the app.

Step 2: Polling for User Authorization

After providing the pairing code or URL code, verify user entry with this request:

curl -X POST https://api.frame.io/v2/auth/token \
    --form 'client_id=[client_id]' \
    --form 'device_code=[device_code]' \
    --form 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
    | python -m json.tool

Payload Parameters

• client_id: The same identifier used in Step 1.
• device_code: The device_code value returned previously.
• grant_type: The OAuth grant type identifier, consistently urn:ietf:params:oauth:grant-type:device_code for this implementation.

Initial polling attempts typically return:

{
  "error": "authorization_pending"
}

This non-fatal error indicates the user hasn’t completed code entry. Continue polling until completion.

If you receive:

{
  "error": "expired_token"
}

The code expired before user entry. Generate a new code/QR code via Step 1, present it to the user, and resume polling.

Successful authorization produces:

{
  "access_token": "[access_token]",
  "expires_in": 28800,
  "refresh_token": "[refresh_token]",
  "token_type": "bearer"
}

Congratulations on successfully authorizing your Camera to Cloud device!

Let’s examine this response:

• access_token: Your authentication credential for Frame.io backend access, required in headers for future API requests.
• expires_in: The access token validity period in seconds, after which refreshing is necessary.
• refresh_token: Used for access token management, primarily for refreshing authorization but also applicable for revocation.
• token_type: Consistently bearer for C2C API implementations, requiring no action.

Putting the Steps Together

Now let’s implement these API calls in Python-like pseudocode, handling potential device code expiration:

1
def authorize_with_frame():
2
    """
3
    Handles authorizing our device with Frame.io.
4
    """
5
6
    # Our client ID can be a serial number, UUID, or some other unique string.
7
    client_id = THIS_DEVICE.get_serial_number()
8
9
    while True:
10
        # Make the call to Frame.io to get our device codes.
11
        pairing_codes = c2c.get_device_codes(client_id)
12
13
        # We need to keep track of how long we have been polling for
14
        polling_started = datetime.now()
15
16
        # Now we are going to poll for authorization until the user enters the code.
17
        while True:
18
19
            # Re-write this output each time we poll. Note: This message will only update once
20
            # per `interval` (e.g., 5 seconds), so if a smooth countdown is desired, that will
21
            # need a different implementation.
22
            print(
23
                f"\rPAIRING CODE: {pairing_codes.user_code}, "
24
                f"EXPIRES IN: {pairing_codes.expires_in - (datetime.now() - polling_started).seconds} seconds"
25
            )
26
27
            # Wait for `interval` before polling each time.
28
            sleep(pairing_codes.interval)
29
30
            # Make a call to Frame.io to see if the user has entered the code and authorized
31
            # the device.
32
            authorization, error = c2c.poll_for_authorization(
33
                client_id, pairing_codes.device_code
34
            )
35
36
            if error and error.message == "authorization_pending":
37
                # If the authorization is pending, try again.
38
                continue
39
            elif error and error.message == "expired_token":
40
                # If the pairing codes have expired, break to generate new codes.
41
                break
42
            elif error:
43
                # If there was some other error, raise it.
44
                raise error
45
            else:
46
                # If there was no error, we have our authorization!
47
                return authorization
48
49
        # If we get here, our pairing codes expired. Let's try again.
50
        print("\nPairing code expired. Generating a new one...")

Note: The outer loop handles cases where pairing codes expire and new codes are required.

As a final step, retrieve and display project information from Frame.io to confirm successful pairing to the intended project. We’ll cover this in the next tutorial.

Creating and Displaying QR Codes for Pairing

When implementing URL/QR code pairing, you’ll need to generate a QR code from the verification_uri_complete value in the response. Here are examples using popular libraries in different programming languages:

Python Example using qrcode

1
import qrcode
2
from PIL import Image
3
import io
4
5
def generate_qr_code(verification_uri_complete, size=250):
6
    """
7
    Generate a QR code from the verification_uri_complete URL.
8
    
9
    Args:
10
        verification_uri_complete (str): The complete verification URI returned by Frame.io
11
        size (int, optional): Size of the QR code in pixels. Defaults to 250.
12
    
13
    Returns:
14
        PIL.Image: QR code image that can be displayed or saved
15
    """
16
    qr = qrcode.QRCode(
17
        version=1,
18
        error_correction=qrcode.constants.ERROR_CORRECT_L,
19
        box_size=10,
20
        border=4,
21
    )
22
    qr.add_data(verification_uri_complete)
23
    qr.make(fit=True)
24
    
25
    img = qr.make_image(fill_color="black", back_color="white")
26
    
27
    # Resize the image if needed
28
    img = img.resize((size, size))
29
    return img
30
31
# Example usage in authorization flow
32
def display_qr_for_pairing(pairing_codes):
33
    """
34
    Generate and display QR code along with manual pairing instructions.
35
    """
36
    if hasattr(pairing_codes, 'verification_uri_complete'):
37
        # Generate QR code from the verification URI
38
        qr_img = generate_qr_code(pairing_codes.verification_uri_complete)
39
        
40
        # Display the QR code on screen
41
        # For GUI applications like Tkinter, PyQt, etc.
42
        # display_image(qr_img)
43
        
44
        # For headless devices or testing, save to file
45
        qr_img.save("frame_io_pairing_qr.png")
46
        
47
        print(f"Scan the QR code or visit: {pairing_codes.verification_uri}")
48
        print(f"Manual code: {pairing_codes.user_code}")
49
    else:
50
        # Fallback for devices that received traditional pairing response
51
        print(f"Enter code on Frame.io: {pairing_codes.user_code}")

JavaScript Example (Web or Electron)

1
import QRCode from 'qrcode';
2
3
/**
4
 * Generate and display a QR code from the verification URI
5
 * @param {string} verificationUriComplete - The complete verification URI from Frame.io
6
 * @param {string} elementId - ID of the HTML element to display the QR code in
7
 */
8
function displayQRCode(verificationUriComplete, elementId = 'qrcode-container') {
9
  const element = document.getElementById(elementId);
10
  
11
  if (!element) {
12
    console.error(`Element with ID ${elementId} not found`);
13
    return;
14
  }
15
  
16
  // Clear any existing content
17
  element.innerHTML = '';
18
  
19
  // Generate QR code
20
  QRCode.toCanvas(element, verificationUriComplete, { width: 250 }, function(error) {
21
    if (error) {
22
      console.error('Error generating QR code:', error);
23
      // Fallback to displaying the URL as a link
24
      element.innerHTML = `<a href="${verificationUriComplete}" target="_blank">Click here to pair</a>`;
25
    }
26
  });
27
  
28
  // Also display manual pairing information
29
  const manualInfoDiv = document.createElement('div');
30
  manualInfoDiv.innerHTML = `
31
    <p>Scan the QR code or <a href="${verificationUriComplete}" target="_blank">click here</a> to pair your device.</p>
32
    <p>Manual code: ${userCode}</p>
33
  `;
34
  element.parentNode.appendChild(manualInfoDiv);
35
}
36
37
// Example usage in authorization flow
38
async function requestDeviceCode() {
39
  try {
40
    const response = await fetch('https://api.frame.io/v2/auth/device/code', {
41
      method: 'POST',
42
      headers: {
43
        'x-client-version': '2.0.0',
44
        'x-client-platypus-enabled': 'true'
45
      },
46
      body: new URLSearchParams({
47
        'client_id': YOUR_CLIENT_ID,
48
        'client_secret': YOUR_CLIENT_SECRET,
49
        'scope': 'asset_create offline'
50
      })
51
    });
52
    
53
    const data = await response.json();
54
    
55
    if (data.verification_uri_complete) {
56
      displayQRCode(data.verification_uri_complete);
57
      window.userCode = data.user_code; // Store for display purposes
58
    } else {
59
      // Fallback for traditional pairing
60
      displayManualPairingCode(data.user_code);
61
    }
62
    
63
    // Begin polling for authorization
64
    beginPollingForAuthorization(data.device_code, data.interval);
65
    
66
  } catch (error) {
67
    console.error('Error requesting device code:', error);
68
  }
69
}

Android Example (Java)

1
import android.graphics.Bitmap;
2
import android.widget.ImageView;
3
import com.google.zxing.BarcodeFormat;
4
import com.google.zxing.MultiFormatWriter;
5
import com.google.zxing.common.BitMatrix;
6
import com.journeyapps.barcodescanner.BarcodeEncoder;
7
8
public void generateAndDisplayQRCode(String verificationUriComplete, ImageView qrCodeImageView) {
9
    try {
10
        MultiFormatWriter multiFormatWriter = new MultiFormatWriter();
11
        BitMatrix bitMatrix = multiFormatWriter.encode(verificationUriComplete, 
12
            BarcodeFormat.QR_CODE, 250, 250);
13
        BarcodeEncoder barcodeEncoder = new BarcodeEncoder();
14
        Bitmap bitmap = barcodeEncoder.createBitmap(bitMatrix);
15
        
16
        // Display in ImageView
17
        qrCodeImageView.setImageBitmap(bitmap);
18
        
19
    } catch (Exception e) {
20
        e.printStackTrace();
21
        // Fallback to displaying the URL as text
22
    }
23
}

iOS Example (Swift)

1
import UIKit
2
import CoreImage
3
4
func generateQRCode(from string: String) -> UIImage? {
5
    let data = string.data(using: String.Encoding.utf8)
6
    
7
    if let filter = CIFilter(name: "CIQRCodeGenerator") {
8
        filter.setValue(data, forKey: "inputMessage")
9
        filter.setValue("H", forKey: "inputCorrectionLevel")
10
        
11
        if let outputImage = filter.outputImage {
12
            // Scale the image
13
            let transform = CGAffineTransform(scaleX: 10, y: 10)
14
            let scaledImage = outputImage.transformed(by: transform)
15
            
16
            // Convert to UIImage
17
            let context = CIContext()
18
            if let cgImage = context.createCGImage(scaledImage, from: scaledImage.extent) {
19
                return UIImage(cgImage: cgImage)
20
            }
21
        }
22
    }
23
    
24
    return nil
25
}
26
27
// Usage in your view controller
28
func displayPairingQRCode(verificationUriComplete: String) {
29
    if let qrCodeImage = generateQRCode(from: verificationUriComplete) {
30
        qrCodeImageView.image = qrCodeImage
31
        
32
        // Also show manual pairing information
33
        pairingInstructionsLabel.text = "Scan the QR code or enter code manually"
34
        pairingCodeLabel.text = userCode
35
    } else {
36
        // Fallback to manual code display
37
        pairingInstructionsLabel.text = "Enter this code on Frame.io:"
38
        pairingCodeLabel.text = userCode
39
    }
40
}

Best Practices for QR Code Display

When implementing QR code pairing, consider these guidelines for the best user experience:

1. Optimal Size: Display QR codes at least 200-250 pixels square for reliable scanning.

2. Contrast: Ensure high contrast between QR code and background (black on white is ideal).

3. Error Correction: Use moderate error correction levels (L or M) to balance code density and reliability.

4. Clear Instructions: Provide clear guidance on how to scan the code, such as “Scan this code with your smartphone camera to pair your device.”

5. Multiple Options: Always provide the manual pairing code alongside the QR code as a fallback:

   Scan to pair:
   [QR CODE]
   Or enter code manually: 573131

6. Hyperlink for Mobile Apps: If your integration is a mobile application, include the verification_uri_complete as a tappable link since users cannot scan a QR code from the same device.

7. Testing: Test your QR codes with various devices and lighting conditions to ensure reliable scanning.

Troubleshooting

If you encounter issues, consult these common scenarios and solutions:

• “Connect Device” Button Not Visible: When accessing the C2C management panel, this could indicate:
  • Insufficient Permissions: If you see a permissions message, contact your account manager to adjust permissions or assign an appropriate role.
  • Existing Device Connection: After connecting one device, the primary “Add New Device” button is replaced by a three-dot menu in the upper-right corner of the C2C Connections panel.
• Invalid Client Error: An invalid_client response indicates device information mismatch, typically due to an incorrect client_secret.
• Bad Request Error: A bad_request response indicates malformed request data. Verify field names and ensure all required fields are included.

If your issue isn’t addressed here, please share your experience so we can enhance this troubleshooting section.

Next Steps

We encourage you to contact our team and proceed to the authorization management guide. We look forward to your feedback!