> This page is for 플랫폼, version 레거시.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 실험적: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - 레거시: https://next.developer.frame.io/platform/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.

# 방법: 권한 부여(하드웨어)

## 소개

이 가이드는 [Frame.io](http://frame.io/) 프로젝트에서 C2C(Camera to Cloud) 하드웨어 디바이스에 대한 인증 및 권한 부여 프로세스를 보여줍니다. 최적의 사용자 경험을 위해 수동 코드 입력을 사용하는 기존 페어링 방법과 향상된 QR 코드 페어링 방식을 모두 다룹니다.

## 무엇이 필요할까요?

[시작하기 전에 구현 전 숙지 사항](link) 가이드를 아직 확인하지 않으셨다면 미리 검토해 주시기 바랍니다. 연동 시스템을 식별하기 위해 저희 팀으로부터 `client_secret`을 발급받으셨을 것입니다. `client_secret`을 받지 못하셨다면 이 C2C 에코시스템 [소개](LINK)를 확인하시고 저희 팀에 문의해 주세요.

### QR 코드 페어링을 위한 전제 조건





QR 코드 페어링을 시작하기 전에 다음 전제 조건이 충족되었는지 확인하세요.





* **기능 플래그 활성화**: [Frame.io](http://frame.io/) 계정에서 특정 기능 플래그(`v4.c2c_qr_code_activate`)가 활성화되어 있어야 합니다. 이 기능 플래그를 통해 QR 코드 기반 페어링 방식에 액세스할 수 있습니다. 지정된 [Frame.io](http://frame.io/) 담당자가 원하는 계정에 이 기능을 활성화하도록 도와드릴 수 있습니다.
* **카메라 호환성**: 디바이스 페어링 프로세스 중에 QR 코드 생성을 지원하도록 카메라 하드웨어가 업데이트되었는지 확인합니다.




## 하드웨어 인증 흐름 살펴보기





구현하고자 하는 권한 부여 흐름에 대해 예상되는 사용자 경험을 전반적으로 이해하고 있어야 합니다. 사용자 관점에서 이 흐름을 파악하려면 다음 리소스를 확인하세요.





* 새 하드웨어 디바이스 추가에 대한 지원 문서입니다.
* Teradek Cube 권한 부여에 대한 교육 비디오입니다.




하드웨어 권한 부여 흐름은 구현자와 디바이스 UI의 부담을 최대한 줄이도록 설계되었습니다. 이 흐름을 사용하면 다음 사항에 대해 걱정할 필요가 없습니다.





* 웹 브라우저로 리디렉션.
* [Frame.io](http://frame.io/) 사용자 로그인/인증 처리
* 연결할 계정 및 프로젝트 나열/선택
* 기본 정보 표시 외의 모든 UI 요소.




### QR 코드 페어링으로 사용자 경험 향상





효율성과 사용 편의성에 대한 요구가 커지면서 사용자는 디바이스와의 원활한 상호 작용을 점점 더 기대하고 있습니다. Frame.io의 C2C 서비스에 카메라를 페어링하는 현재 프로세스는 페어링 코드를 수동으로 입력하는 것을 포함하여 여러 단계가 필요합니다. 기능적으로는 문제가 없지만 이 프로세스를 더욱 간소화할 수 있습니다.





Netflix나 Disney+와 같은 스트리밍 서비스에서 볼 수 있는 디바이스 페어링 경험과 유사하게 QR 코드를 활용하면 프로세스를 단순화하고 수동 입력으로 인한 오류를 제거하며 카메라 페어링에 소요되는 시간을 단축할 수 있습니다.






## 디바이스 식별(client_id)





Camera to Cloud에 연결할 때 사용자의 프로젝트에 디바이스 연결을 나열할 수 있도록 각 물리적 하드웨어 디바이스를 고유하게 식별해야 합니다.

하드웨어 디바이스의 경우, 사용하기로 선택한 권한 부여 패턴에 따라 이를 디바이스의 `client_id`라고 합니다. 구현을 설정할 때 이 작업을 어떻게 수행할지 고려해야 합니다. 하드웨어 디바이스의 일련번호, UUID 또는 특정 고유 식별 문자열을 사용할 수 있습니다. 개인 식별 정보가 유출되지 않도록 주의하세요. 예를 들어 사용자의 이메일은 `client_id`로 사용하기에 적합한 값이 아닙니다.

마찬가지로 반드시 고유 식별자를 직접 제어할 수 있어야 합니다. C2C API를 소프트웨어 디바이스로 구현하는 경우, 예를 들어 디바이스의 MAC 주소를 사용해서는 안 됩니다. MAC 주소는 귀하의 소프트웨어 소유가 아니며 개인 식별 정보로 간주될 수도 있습니다.





어떤 값을 사용해야 할지 잘 모르겠다면 함께 상의하여 연동을 최대한 간소화할 수 있는 적절한 값을 선택하도록 도와드릴 수 있습니다.






## 1단계: 디바이스 코드 요청

본격적으로 구현을 시작해 보겠습니다. 가장 먼저 해야 할 일은 사용자에게 디바이스용으로 제공할 디바이스 코드를 요청하는 것입니다. 이를 위해 `/v2/auth/device/code` 엔드포인트를 호출합니다.

### 기존 페어링 방식





```
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
```







### QR 코드 페어링 활성화





QR 코드 기반 페어링을 활성화하려면 API 호출을 약간 수정해야 합니다. 특히 디바이스 코드 요청에 두 개의 새로운 헤더를 추가해야 합니다. 이를 통해 디바이스가 페어링 페이지에 직접 연결되어 페어링 프로세스를 간소화할 수 있습니다.






```
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 QR code
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool
```

**참고:** 여기서는 JSON 데이터가 아닌 양식 데이터를 사용하고 있습니다. C2C 인증 엔드포인트는 양식 데이터만 허용합니다. 인증이 완료되면 다른 엔드포인트는 JSON 페이로드를 허용하지만, 인증 엔드포인트에 JSON 페이로드를 전송하면 오류가 반환됩니다.

#### 페이로드 매개변수




* **client_id**: 물리적 하드웨어 디바이스의 고유 식별자입니다. 이 값은 디바이스에 대해 고유성이 보장되어야 합니다. 일련번호나 임의로 생성된 UUID일 수 있습니다.
* **client_secret**: 디바이스 모델을 식별하기 위해 [Frame.io](http://frame.io/) 지원팀에서 발급합니다. 이 값은 사용자로부터 비밀로 유지되어야 하며 저장 시 암호화되어야 합니다.
* **scope**: 요청하는 권한이며 공백을 구분 기호로 사용합니다. 하드웨어 디바이스는 다음 두 가지 권한만 요청할 수 있습니다.
* `asset_create`: 디바이스가 에셋을 생성하고 업로드할 수 있도록 허용합니다.
* `offline`: 디바이스가 새로 고침 토큰을 사용하여 자체 권한 부여를 새로 고칠 수 있도록 허용합니다. 권한 부여 토큰은 8시간 후에 만료되므로 이 권한이 없으면 사용자는 8시간마다 디바이스를 다시 인증해야 합니다.




실제 적용 시 디바이스는 거의 항상 두 가지 권한을 모두 요청해야 합니다.






### API 응답 이해





요청을 하면 다음과 유사한 응답을 받게 됩니다.






#### 기존 페어링 응답





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







#### QR 코드 페어링 응답





```
{
  "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"
}
```







#### 응답 분석




* **device_code**: 디바이스 코드는 사용자에게 표시되지 않아야 하며, 사용자가 코드를 올바르게 입력했는지 확인하기 위해 폴링할 때 이 권한 부여 요청을 식별하는 데 사용됩니다.
* **expires_in**: 이 코드가 만료될 때까지 남은 시간(초 단위)입니다.
* **interval**: 사용자가 코드를 입력했는지 확인하기 위한 폴링 요청 사이에 기다려야 하는 시간입니다.
* **name**: 연결하려는 디바이스의 이름입니다.
* **user_code**: 사용자가 디바이스를 프로젝트에 페어링하기 위해 [Frame.io](http://frame.io/)에 입력할 6자리 코드입니다.
* **verification_uri**: QR 코드가 스캔되지 않은 경우 사용자가 수동으로 입력할 URL입니다. 간결하고 기억하기 쉬워야 합니다.
* **verification_uri_complete**: 이 URL에는 페어링 코드가 포함되어 있으며 비텍스트 방식 전송(예: QR 코드)을 위한 것입니다. 스캔 시 디바이스를 연결할 계정과 프로젝트를 선택하는 페어링 환경으로 사용자를 자동 라우팅합니다.




### 사용자에게 QR 코드 표시

이제 `verification_uri_complete`를 얻었으므로 이 URL에서 QR 코드를 생성하여 디바이스 화면을 통해 사용자에게 표시할 수 있습니다. 이를 통해 사용자는 모바일 디바이스나 카메라로 QR 코드를 스캔하기만 하면 되므로 페어링 프로세스가 간소화됩니다.

#### 예시: QR 코드가 표시된 카메라 화면





*QR 코드가 표시된 카메라 화면의 이미지 또는 일러스트레이션을 삽입합니다.*

사용자가 어떤 이유로든 QR 코드를 스캔할 수 없는 경우를 대비하여 대체 수단으로 수동으로 페어링 코드를 입력할 수 있도록 `user_code`와 `verification_uri`를 함께 표시해야 합니다. 또는 사용자가 모바일 디바이스로 스캔할 수 있도록 `verification_uri`를 정적 QR 코드로 표시할 수도 있습니다. 연동 시스템이 모바일 디바이스의 앱인 경우, 앱이 실행 중인 동일한 디바이스에서는 QR 코드를 스캔할 수 없으므로 사용자가 탭할 수 있는 하이퍼링크로 `verification_uri_complete`를 표시해야만 원활한 연결이 가능합니다.

## 2단계: 사용자 권한 부여 폴링





페어링 코드를 제공하거나 QR 코드를 사용자에게 표시한 후에는 코드를 입력했는지 확인해야 합니다. 이를 위해 다음과 같은 요청을 할 수 있습니다.






```
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
```







### 페이로드 매개변수




* **client_id**: 1단계에서 전송한 것과 동일한 `client_id`입니다.
* **device_code**: `/v2/auth/device/code`에서 반환된 `device_code`입니다.
* **grant_type**: OAuth 시스템이 발급하는 권한 부여 유형입니다. 이 값은 항상 `urn:ietf:params:oauth:grant-type:device_code`입니다.




처음 몇 번 이 요청을 수행할 때는 다음과 같은 응답을 받을 가능성이 높습니다.






```
{
  "error": "authorization_pending"
}
```






하지만 걱정하지 마세요! 이 오류는 시스템 오류가 아닙니다. 이는 단순히 사용자가 Frame.io UI에 사용자 코드를 아직 입력하지 않았음을 의미합니다. 우리는 사용자가 코드를 입력할 때까지 계속 폴링만 하면 됩니다.





만약 그 대신 다음과 같은 오류가 발생한다면:






```
{
  "error": "expired_token"
}
```






이는 사용자가 코드를 입력하기 전에 코드가 만료되었음을 의미합니다. 이러한 경우 1단계를 사용하여 새 페어링 코드나 QR 코드를 생성하여 사용자에게 표시한 다음 폴링을 재개해야 합니다.





최종적으로는 다음과 같은 응답을 받아야 합니다.






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






응답 페이로드가 이와 같다면: 축하합니다! 첫 번째 Camera to Cloud 디바이스에 성공적으로 권한을 부여했습니다. 잠시 이 기쁨을 만끽하세요!





기쁨을 만끽한 후에는 응답 페이로드를 살펴보고 그 내용을 확실히 이해해 보겠습니다.





* **access_token**: [Frame.io](http://frame.io/) 백엔드의 나머지 부분에 액세스하기 위한 키입니다. 이 튜토리얼에서 수행할 나머지 요청의 헤더에 이를 추가해야 합니다.
* **expires_in**: `access_token`이 만료될 때까지 남은 시간(초 단위)입니다. 토큰 시간이 만료되면 새로 고쳐야 하며, 이는 향후 튜토리얼에서 다룰 예정입니다.
* **refresh_token**: `access_token`을 관리하는 데 사용할 수 있는 토큰입니다. 대부분 권한 부여를 새로 고치는 데 사용되지만 권한 부여를 취소하는 데 사용할 수도 있습니다.
* **token_type**: C2C API의 경우 항상 `bearer`가 되며 추가적인 조치가 필요하지 않습니다.




## 단계 조합하기





이제 호출해야 할 API를 알았으므로 이를 Python 형태의 의사 코드로 조합해 보겠습니다. 디바이스 코드는 만료될 수 있으므로 로직을 설정할 때 이러한 가능성을 반드시 처리해야 합니다.






**`Python`**

```python title="Python"
def authorize_with_frame():
    """
    Handles authorizing our device with Frame.io.
    """

    # Our client ID can be a serial number, UUID, or some other unique string.
    client_id = THIS_DEVICE.get_serial_number()

    while True:
        # Make the call to Frame.io to get our device codes.
        pairing_codes = c2c.get_device_codes(client_id)

        # We need to keep track of how long we have been polling for
        polling_started = datetime.now()

        # Now we are going to poll for authorization until the user enters the code.
        while True:

            # Re-write this output each time we poll. Note: This message will only update once
            # per `interval` (e.g., 5 seconds), so if a smooth countdown is desired, that will
            # need a different implementation.
            print(
                f"\rPAIRING CODE: {pairing_codes.user_code}, "
                f"EXPIRES IN: {pairing_codes.expires_in - (datetime.now() - polling_started).seconds} seconds"
            )

            # Wait for `interval` before polling each time.
            sleep(pairing_codes.interval)

            # Make a call to Frame.io to see if the user has entered the code and authorized
            # the device.
            authorization, error = c2c.poll_for_authorization(
                client_id, pairing_codes.device_code
            )

            if error and error.message == "authorization_pending":
                # If the authorization is pending, try again.
                continue
            elif error and error.message == "expired_token":
                # If the pairing codes have expired, break to generate new codes.
                break
            elif error:
                # If we get another error, we should raise it. (advanced error handling will
                # be covered in another tutorial)
                raise Exception(error.message)

            return authorization
```

**참고:** 이 의사 코드에서는 페어링 코드가 만료되어 새 코드를 요청해야 하는 경우를 처리하기 위해 외부 루프를 추가했습니다. 마지막으로 수행해야 할 작업은 연동한 프로젝트에 대한 정보를 [Frame.io](http://frame.io/)에서 가져와 사용자에게 표시함으로써 디바이스가 의도한 프로젝트에 올바르게 페어링되었음을 다시 한번 확인시켜 주는 것입니다. 이는 다음 튜토리얼에서 보여드리겠습니다.

## 문제 해결





여기까지 오셨다면 무언가 잘못된 것입니다! 어떤 종류의 오류도 발생하지 않는다면 서드 파티 연동이 아니겠죠? 이 섹션에서는 일반적인 문제들을 나열하고 이를 해결할 가능성이 가장 높은 단계를 안내합니다. 다음 목록을 살펴보고 귀하가 겪고 있는 문제와 일치하는 사항이 있는지 확인해 보세요.





여기서 해결책을 찾지 못하셨다면 나중에 추가할 수 있도록 겪으신 문제를 공유해 주시면 감사하겠습니다.





* **"디바이스 연결" 버튼이 보이지 않음**: C2C 관리 패널로 이동했는데 "디바이스 연결" 버튼이 보이지 않는다면 다음 두 가지 중 하나가 원인입니다.
* ~~**C2C가 계정에 대해 활성화되지 않음**: 화면이 비어 있고 계정에서 C2C를 사용할 수 없다는 메시지가 표시되는 경우, 계정 관리자가 계정 설정에서 프로젝트에 대해 C2C를 활성화해야 합니다.~~
* **디바이스 관리자가 아님**: 화면이 비어 있고 권한이 없다는 메시지가 표시되는 경우, 계정 관리자가 C2C 디바이스를 연결할 수 있는 사용자의 권한을 변경하거나 귀하를 해당 권한이 있는 역할에 추가해야 합니다.
* **이미 연결된 디바이스가 있음**: 첫 번째 디바이스가 연결되면 커다란 파란색 "새 디바이스 추가" 버튼이 사라지며, 대신 C2C Connections 패널의 우측 상단에 있는 점 3개 메뉴를 클릭해야 합니다.
* **잘못된 클라이언트 오류**: 제공한 디바이스 정보가 저희 시스템에 등록된 정보와 일치하지 않을 때 `invalid_client`가 반환됩니다. 이는 `client_secret`이 잘못되었을 가능성이 높음을 의미합니다.
* **잘못된 요청 오류**: 요청 데이터의 형식이 잘못되었을 때 `bad_request`가 반환됩니다. 필드 이름의 철자가 틀렸거나 필수 필드를 누락하지 않았는지 다시 한번 확인하세요.




## 다음 단계





아직 문의하지 않으셨다면 저희 팀에 문의하신 후 다음 가이드로 계속 진행하시기 바랍니다: [LINK](). 여러분의 연락을 기다리겠습니다!





* * *





## 추후 고려 사항





할 일




동적 QR 코드를 생성할 수 없는 파트너를 위한 대비책 추가

백업 계획으로 "`**verification_uri**`로 이동하여 이 코드를 입력하세요"라고 표시하도록 안내