권한 (Scope)

앱이 요청할 수 있는 권한(Scope)과 권한마다 호출할 수 있는 API 입니다. 앱은 등록할 때 쓸 권한을 선언하고, 스트리머가 동의한 권한 안에서만 API 를 호출합니다.

Scope 목록

'허용하는 작업' 문구는 스트리머의 동의 화면에 그대로 나옵니다. 쓰기 권한에는 조회가 들어 있지 않습니다. 예를 들어 commands:write 만 받은 앱은 명령어를 추가·수정·삭제할 수 있지만 목록 조회는 403 입니다. 앱에 필요한 권한만 요청하세요.

Scope 별 API

WebSocket 은 events:subscribe 가 없으면 연결 직후 4401 로 닫힙니다. 이 연결이 받을 수 있는 이벤트는 연결 직후 오는 connected 메시지의 events 로 확인합니다. 명령어 이벤트에 필요한 것은 조회 권한 commands:read 이니, REST 명령어 수정 권한인 commands:write 와 헷갈리지 마세요. 이벤트 형식은 이벤트 종류에 있습니다.

요청 규칙

• 앱을 등록할 때 쓸 권한을 1개 이상 선언합니다. 인가 요청의 scope 는 선언한 권한 안에서만 고를 수 있습니다.
• 여러 권한은 공백으로 구분합니다(commands:read events:subscribe). 쉼표로 구분해도 되며, 같은 권한을 두 번 적으면 하나로 칩니다.
• scope 가 비었거나, 없는 권한이 있거나, 앱이 선언하지 않은 권한이 있으면 동의 화면 없이 invalid_scope 입니다. 이미 이 앱에 동의한 스트리머면 콜백으로 error=invalid_scope 가 돌아오고, 아니면 인가할 수 없습니다 화면에서 멈춥니다(콜백 오류).
• 스트리머는 요청한 권한을 한꺼번에 허용하거나 거부합니다. 일부만 허용할 수는 없습니다.
• 이미 동의한 범위 안의 권한만 다시 요청하면 동의 화면 없이 바로 코드가 돌아오고 동의 범위도 그대로입니다.
• 동의한 범위를 넘는 권한을 요청해 다시 허용받으면 동의 범위는 이전 동의에 더해지지 않고 이번 요청의 권한으로 바뀝니다. 계속 쓸 권한까지 모두 담아 요청하세요.
• 실제로 받은 권한은 토큰 응답의 scope 로, 지금 쓸 수 있는 권한은 토큰 정보 (me)의 scopes 로 확인합니다.

권한을 선언하지 않고 등록한 옛 앱은 모든 권한을 요청할 수 있습니다. 앱 목록에 권한 미선언 — 전체 허용 으로 표시되며, 앱 상세에서 권한을 골라 저장하면 그때부터 선언 범위를 검사합니다.

권한 변경과 기존 토큰

API 를 호출할 때마다 토큰의 권한 ∩ 스트리머의 현재 동의 ∩ 앱이 선언한 권한을 다시 계산하고 그 범위만 허용합니다. 셋이 겹치는 권한이 하나도 없으면 토큰을 쓸 수 없어 403 이 아니라 401 이 됩니다. 열린 WebSocket 도 메시지를 주고받을 때와 30초마다 다시 확인합니다.

권한을 선언하지 않은 옛 앱에 처음 권한을 선언해 저장하는 것도 '권한을 뺌'으로 처리합니다. 앱 상세에서 권한을 줄이면 몇 건이 좁혀지거나 해제됐는지 알려 줍니다. 화면 설명은 권한을 줄이거나 앱 삭제하기에 있습니다.