API 키 관리 | 설명서 - Roblox 크리에이터 허브

Open Cloud는 API 키를 사용하여 API 접근을 인증하고 권한을 부여하며, 이를 통해 데이터 스토어 및 장소와 같이 게임의 특정 리소스에 대한 세분화된 권한 및 보안 제어를 추가할 수 있습니다.

모든 Open Cloud API는 유효한 권한이 있는 API 키를 생성하고 요청에 x-api-key 헤더를 포함해야 하며, 이를 통해 애플리케이션이 사용자를 대신하여 Open Cloud에 인증할 수 있습니다.

API 키 생성

아래 텍스트에 API 키에 대한 모든 참조는 사용자 소유의 키를 가리킵니다.

리소스에 접근하기 위해 API 키를 생성하고 구성할 수 있습니다. API 키의 접근 권한은 키를 소유한 사용자의 권한에 의해 결정됩니다. 이는 일반적으로 사용자가 권한을 가진 모든 리소스에 접근할 수 있음을 의미합니다. 여기에는 개인 게임이나 적절한 역할이 있는 그룹 소유 게임도 포함됩니다. 특정 범위는 특정 게임으로 제한될 수 있지만, 모든 경우에 해당하지는 않습니다.

그룹 리소스를 관리하기 위해 API 키를 생성하는 방법에 대한 자세한 내용은 아래의 그룹 소유 리소스 관리를 위한 API 키 생성 섹션을 참조하십시오.

API 키를 생성하려면:

Creator Dashboard에서 API Keys 페이지로 이동합니다.
Create API Key 버튼을 클릭합니다.
API 키의 고유한 이름을 입력합니다. 나중에 용도를 기억할 수 있도록 PLACE_PUBLISHING_KEY와 같은 이름을 사용하십시오.
Access Permissions 섹션에서 Select API System 메뉴에서 API를 선택합니다. 여러 API를 키에 추가해야 하는 경우 이 단계를 반복하십시오.
해당하는 경우, API 키로 접근할 게임을 선택합니다.

Restrict by Experience를 선택적으로 비활성화할 수 있습니다. 비활성화하면 API 키가 사용자 소유의 모든 게임과 웅장 소유 게임, 그리고 미래에 생성하는 모든 게임에 접근할 수 있습니다.
Select Operations 드롭다운에서 API 키에 대해 활성화할 작업을 선택합니다.

API reference의 대부분의 작업은 필요한 권한 범위를 포함합니다. 예를 들어, flush memory store 작업은 universe.memory-store:flush 권한이 필요합니다.

모든 범위와 해당 API를 지원하는 목록은 Scopes에서 확인할 수 있습니다.
(선택 사항) Security 섹션에서 CIDR notation을 사용하여 키에 대한 IP 접근을 명시적으로 제한합니다. 로컬 컴퓨터의 IP 주소를 찾아 Accepted IP Addresses 섹션에 추가하고 추가 IP 주소를 추가할 수 있습니다. 고정 IP가 없거나 API 키를 로컬 환경에서만 사용하는 경우, Restrict IP addresses 토글을 체크 해제하여 모든 IP가 API 키를 사용할 수 있도록 할 수 있습니다.
(선택 사항) 리소스에 대한 추가 보호를 위해 키의 만료 날짜를 설정합니다.
Save & Generate key 버튼을 클릭합니다.
API 키 문자열을 안전한 위치에 복사하여 저장합니다. 코드의 공개 리포지토리에 저장하지 마십시오.
Creator Dashboard의 API Extensions 페이지에서 API 키의 상태를 확인합니다.

API 키 문자열은 애플리케이션의 비밀번호와 같습니다. 개발 팀 외부의 신뢰할 수 없는 사람들과 절대 공유하지 마십시오.

그룹 소유 리소스 관리를 위한 API 키 생성

API 키는 사용자가 권한을 가진 모든 리소스에 대한 접근을 부여합니다. 여기에는 그룹 외부의 개인 게임도 포함됩니다. 퍼스널 계정의 API 키를 그룹 자동화에 사용하고 해당 키가 손상되면, 사용자가 접근하는 다른 리소스도 위험에 처하게 됩니다.

이를 방지하기 위해, 강력히 권장합니다. 그룹에 대한 접근 권한이 엄격하게 제한된 전용 대체 계정에서 별도의 API 키를 생성하는 것입니다. 이 자동화 전용 계정에는 최소한의 권한만 부여하여 대상 그룹에만 접근할 수 있도록 하십시오.

자동화를 위해 새로운 전용 Roblox 계정을 생성합니다.
새 계정을 그룹에 초대합니다.
작업에 최소한의 권한이 있는 그룹 역할을 할당합니다 (예: "Create and edit group experiences"만 허용).
새 계정으로 로그인하고 위 섹션의 API 키 생성 단계를 따릅니다.
생성된 API 키를 사용하여 그룹 리소스 자동화에 적용합니다.

API 키 관리에 대한 모범 사례

API 키는 데이터에 대한 무단 접근을 방지하기 위해 안전하게 보관해야 하는 민감한 자격 증명입니다. 다음은 API 키를 관리하기 위한 모범 사례입니다.

각 애플리케이션마다 별도의 키 생성: 각 애플리케이션 또는 사용 사례에 대해 별도의 API 키를 생성하여 접근을 분리하고 키가 손상될 경우 영향을 줄이는 것이 좋습니다.
필요한 최소 권한 선택: 범위 구성을 할 때 키의 의도된 사용을 위해 필요한 최소한의 권한을 선택합니다. 범위 접근을 게임으로 제한할 수 있는 경우, 필요한 특정 게임으로만 접근을 제한합니다.
IP 주소 제한 사용: API 키 접근을 특정 IP 주소 또는 CIDR 범위로 제한하여 무단 사용을 방지합니다. Roblox 장소에서 API 키를 사용할 때는 IP 주소 제한을 사용하지 않도록 하여 키가 Roblox 서버와 함께 사용될 수 있도록 합니다.
만료 날짜 설정: 단기 사용 사례의 경우, 설정한 기간 후에 자동으로 키를 비활성화하기 위해 만료 날짜를 구성합니다. 키가 손상될 위험을 줄입니다. 키 회전 과정이 없는 긴 기간 사용 사례에 대해서는 만료 날짜를 설정하는 것이 권장되지 않으며, 만료될 경우 자동화가 예상치 못하게 실패할 수 있습니다.
그룹 리소스 관리를 위한 전용 대체 계정 사용: 그룹 소유 리소스 관리를 위한 API 키 생성 섹션에 자세히 설명된 대로, 그룹 리소스 관리를 위해 최소 권한을 가진 전용 계정을 사용합니다.
API 키를 안전하게 보관: API 키를 소스 코드, 버전 제어 시스템 또는 노출될 수 있는 스크립트에 직접 저장하지 마십시오. 키를 저장하고 접근 규제를 위해 비밀 관리 시스템을 사용하십시오. Roblox 장소에서는 Secrets Store를 사용하십시오.
공공 채널을 통한 API 키 공유 금지: API 키를 공개적인 커뮤니케이션 채널, 포럼 또는 소셜 미디어를 통해 절대 공유하지 마십시오. 믿을 수 있는 팀원과의 안전한 비공식 채널을 통해서만 키를 공유하십시오. 키가 손상될 경우의 영향을 최소화하기 위해 키를 공유하는 사람을 제한하십시오.

CIDR 형식

리소스를 추가로 보호하기 위해, API 키 생성 시 API 키에 접근할 수 있는 IP 주소를 일반 IP 주소나 CIDR 표기법을 사용하여 지정합니다. CIDR IP 주소는 일반 IP 주소처럼 보이지만, 슬래시와 함께 네트워크 라우팅에 중요한 비트 수를 나타내는 10진수가 끝납니다:

일반: 192.168.0.0
CIDR: 192.168.0.0/24

앞부분은 IP 주소이며, 뒷부분은 이진 형식으로 1의 비트를 세는 넷마스크입니다. 이전 예에서 24는 255.255.255.0(24개의 1)으로, 192.168.0.0과 192.168.0.255 사이의 모든 IP에 대한 접근을 허용합니다. CIDR 형식을 이해하는 것은 서버에서 애플리케이션을 실행 계획이 있는 경우에 특히 유용합니다.

API 키 상태

API 키는 처음에 활성 상태로 시작하지만, 시간이 지남에 따라 비활성 상태가 될 수 있습니다. API 키가 상태를 변경한 이유와 활성 상태로 되돌리는 방법에 대한 내용은 다음 표를 참조하십시오.

여러분이나 여러분의 그룹이 API 키를 60일 동안 사용하거나 업데이트하지 않으면, 설정된 만료 날짜가 없어도 자동으로 만료됩니다. 이는 나쁜 행위자가 오래된 API 키를 사용할 수 있는 위험을 감소시킵니다. 더 이상 API 키를 사용하지 않는 경우, 수동으로 비활성화 또는 삭제해야 합니다.

상태	이유	해결책
활성	문제 없음. 사용자는 키를 사용하여 API 호출을 인증할 수 있습니다.	N/A
비활성	사용자가 Enable Key 토글을 비활성화하여 키가 비활성화되었습니다.	Enable Key 토글을 활성화합니다.
만료됨	키의 만료 날짜가 지났습니다.	제거하거나 새로운 만료 날짜를 설정하십시오.
자동 만료	사용자가 지난 60일 동안 키를 사용하거나 업데이트하지 않았습니다.	Enable Key 토글을 비활성화한 후 활성화하거나, 이름, 설명 또는 만료 날짜와 같은 키의 속성을 업데이트할 수 있습니다.
취소됨	그룹 키에 대해서만 해당됩니다. 키를 생성한 계정이 그룹의 키를 관리할 수 있는 충분한 접근 권한이 더 이상 없습니다.	Regenerate Key를 클릭하여 새 비밀을 가져옵니다.
관리됨	보안상의 이유로 Roblox 관리자에 의해 키의 비밀이 변경되었습니다.	Regenerate Key를 클릭하여 새 비밀을 가져옵니다.
사용자 관리됨	키를 생성한 계정이 Roblox에 의해 관리 중입니다.	계정에서 관리 문제를 해결하십시오.

API 키 정보 조회

POST api-keys/v1/introspect

API 키에 대한 정보를 검색합니다. 요청자의 IP 주소에서 키를 사용할 수 있는지와 키 또는 마지막 생성 사용자가 관리되고 있는지 여부를 확인합니다.

요청

(application/json)

Key	Value
apiKey	<api_key>

예제 Introspection API Key 요청
curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key"
}'

응답

각 범위 객체에 포함될 수 있는 네 가지 가능한 리소스 식별자가 있습니다:

userId
groupId
universeId
universeDatastore

userId 및 groupId 식별자는 creator 대상에만 관련이 있습니다. universeDatastore 식별자는 universe-datastore 대상에만 관련이 있습니다. 리소스 식별자는 리소스 선택을 지원하지 않는 범위의 경우 생략됩니다.

리소스 식별자 목록에서 별표(*)는 범위가 해당 유형의 모든 리소스에 대한 권한이 있음을 나타냅니다.

예제 Introspection API Key 응답
{
  "name": "test key",
  "authorizedUserId": 234,
  "scopes": [
    {
      "name": "universe-datastores.objects",
      "operations": [
        "create"
      ],
      "universeDatastores": [
        {
          "universeId": "123",
          "datastoreName": "playerData"
        }
      ]
    },
    {
      "name": "asset",
      "operations": [
        "write"
      ],
      "groupIds": [
        "*"
      ],
      "userIds": [
        "*"
      ]
    }
  ],
  "enabled": true,
  "expired": false,
  "expirationTimeUtc": "2026-01-01T12:00:00.000Z"
}