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

Open Cloud는 API 키를 사용하여 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 참조의 대부분의 작업에는 필요한 권한 범위가 포함되어 있습니다. 예를 들어, flush memory store 작업은 universe.memory-store:flush 권한이 필요합니다.

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

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

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

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

이를 방지하기 위해, 강력히 권장하는 것은 대상 그룹에 대한 접근이 엄격히 제한된 전용 대체 계정에서 별도의 API 키를 생성하는 것입니다. 자동화 목적으로 전용으로 설정된 이 새로운 계정은 대상 그룹에만 접근할 수 있도록 하고, 작업에 필요한 최소한의 권한만 부여해야 합니다.

자동화를 위한 새로운 전용 Roblox 계정을 생성합니다.
새로운 계정을 그룹에 초대합니다.
작업에 필요한 최소 권한을 가진 그룹 역할을 할당합니다(예: "그룹 경험 생성 및 편집만 허용").
새로운 계정으로 로그인하고 위 섹션의 단계를 따라 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 주소와 비슷하지만 슬래시와 함께 네트워크 라우팅에 중요한 비트 수를 나타내는 소수로 끝납니다:

일반: 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 키를 다시 활성 상태로 되돌리는 방법에 대한 내용은 다음 표를 참조하세요.

귀하 또는 귀하의 그룹이 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)

키	값
apiKey	<api_key>

예제 API 키 정보 조회 요청

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 식별자는 생성자 대상을 가진 범위에만 관련이 있습니다. universeDatastore 식별자는 universe-datastore 대상을 가진 범위에만 관련이 있습니다. 리소스 식별자는 리소스 선택을 지원하지 않는 범위에 대해서는 생략됩니다.

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

예제 API 키 정보 조회 응답

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