API 키 관리

Roboflow REST API, roboflow api-key CLI 또는 MCP server를 사용해 워크스페이스 API 키를 프로그래밍 방식으로 생성, 목록 조회, 업데이트, 보호 및 취소합니다.

정보

Roboflow API를 사용하여 워크스페이스의 API 키를 프로그래밍 방식으로 관리할 수 있습니다. 새 키 생성, 기존 키 목록 조회 및 확인, 이름 변경, 메타데이터 추가, 비활성화, 보호, 철회가 가능합니다.

이는 다음이 사용하는 동일한 인터페이스입니다: roboflow api-key CLI 그리고 Roboflow MCP 서버, 따라서 자동화 에이전트는 사람이 대시보드에서 복사해 붙여넣지 않아도 애플리케이션에 필요한 키를 프로비저닝할 수 있습니다.

비밀 값은 한 번만 기록됩니다. 전체 키 값은 반환됩니다 오직 키를 생성(또는 롤링)할 때만. 다른 모든 엔드포인트는 비밀이 아닌 keyId 핸들과 짧은 접두사 식별용입니다 - 절대 키 자체가 아닙니다. 값을 안전하게 저장하세요(예: .gitignore에 포함된 .env) 생성 시에.

HTTP API

인증

API 키를 다음으로 보내세요: api_key 쿼리 매개변수 또는 Authorization: Bearer <api_key> 헤더로 보내면 됩니다. 이는 다른 모든 REST 엔드포인트와 동일합니다(참조: REST API로 인증하기). 사용되는 키는 경로의 워크스페이스에 속해야 합니다.

이 엔드포인트들은 Roboflow의 역할 및 권한. 호출자가 사용자를 대신하는 OAuth 토큰일 때, 관련 RBAC 작업(create_api_key, update_api_key, revoke_api_key, get_api_key, view_workspace_api_keys)의 기본값은 워크스페이스 소유자/관리자. 범위가 지정된 키(또는 사용자를 대신하는 OAuth 토큰)로 보낸 요청은 호출자 자신이 이미 보유한 능력만 생성하거나 부여할 수 있습니다 - 참조: 권한 하위집합 규칙.

호출자가 다음인 경우 범위가 지정된(비 OAuth) 개인 키, 추가로 다음을 포함해야 합니다: 범위 엔드포인트와 일치해야 합니다:

엔드포인트

필요한 범위

GET 목록 / GET 단일

api-key:read

POST 생성

api-key:create

PATCH 업데이트

api-key:update

DELETE 철회

api-key:revoke

GET 공개용

workspace:read

범위가 지정되지 않은(전체 액세스) 개인 키는 이미 이 모든 조건을 충족합니다. 필요한 범위가 없는 키는 마치 해당 경로가 존재하지 않는 것처럼 처리됩니다 - 참조: 오류.

하나의 공개용 키 (rf_<workspaceId>)는 아닙니다 이 관리 엔드포인트의 인증 수단으로 허용되지 않습니다. 개인 키로 인증하세요.

API 키 목록 조회

GET /:workspace/api-keys

워크스페이스의 API 키(마스킹됨)를 나열하고 워크스페이스의 공개용 키를 반환합니다.

쿼리

이름

유형

설명

필수

api_key

문자열

해당 워크스페이스의 개인 API 키.

includeDisabled

불리언

결과에 비활성화된 키를 포함합니다(기본값 false).

includeFolders

불리언

폴더 범위 키의 폴더 세부 정보를 채웁니다(기본값 false).

요청 예시

curl --location 'https://api.roboflow.com/<workspace_id>/api-keys?api_key=$ROBOFLOW_API_KEY'

응답

{
  "apiKeys": [
    {
      "keyId": "9f8c1a2b3d4e5f60",
      "name": "production-server",
      "prefix": "abcd",
      "scopes": ["model:infer"],
      "folderIds": [],
      "default": false,
      "protected": true,
      "disabled": false,
      "created_on": "2026-06-19T18:24:01.000Z",
      "created_by": "user_abc123",
      "custom_metadata": { "env": "prod" }
    }
  ],
  "publishableKey": "rf_<workspace_id>"
}

참고:

keyId 다른 엔드포인트에서 키를 식별하는 데 사용되는 안정적인 비비밀 핸들입니다.
scopes 는 null 범위가 지정되지 않은(전체 액세스) 키의 경우, 또는 다음의 배열: 범위 문자열 범위가 지정된 키의 경우.
created_on (ISO 8601) 및 created_by 해당 값이 기록된 키에만 포함됩니다. 이 속성 추적이 시작되기 전에 생성된 이전 키에는 포함되지 않습니다.
created_by 다음입니다 불투명한 키를 만든 사람을 식별하는 식별자입니다 - 사용자 ID, api_key:<handle> (키가 다른 API 키에 의해 생성된 경우), 또는 SYSTEM (자동화된 프로세스가 생성). 표시/감사용 문자열로 취급하고, 파싱하지 마세요.
custom_metadata 포함됩니다 오직 워크스페이스의 요금제에 고급 API 키 기능이 포함된 경우에만. 해당 기능이 없으면 이 필드는 완전히 존재하지 않습니다(메타데이터가 있는 키라도 마찬가지).

단일 API 키 조회

GET /:workspace/api-keys/:keyId

해당 keyId 핸들.

요청 예시

curl --location 'https://api.roboflow.com/<workspace_id>/api-keys/<key_id>?api_key=$ROBOFLOW_API_KEY'

응답

{ "apiKey": { "keyId": "9f8c1a2b3d4e5f60", "name": "production-server", "prefix": "abcd", "scopes": ["model:infer"], "folderIds": [], "default": false, "protected": true, "disabled": false, "created_on": "2026-06-19T18:24:01.000Z", "created_by": "user_abc123" } }

해당 keyId 워크스페이스에 존재하지 않습니다(또는 철회되었습니다), 또는 자격 증명에 다음이 없습니다: api-key:read 범위가 없거나 / 속하지 않는 워크스페이스를 대상으로 합니다. 권한 사례는 객체 형태의 오류를 반환합니다 {"error": {"message", "type", "hint"}}; 알 수 없는 keyId 다음이 반환됩니다 {"error": "string"}로 구성됩니다. 오류.

API 키 생성

POST /:workspace/api-keys

새 API 키를 생성합니다. 비밀 값은 한 번 에서 키 필드에서 반환됩니다.

헤더

이름

값

Content-Type

application/json

본문

이름

유형

설명

필수

name

문자열

키에 대한 사람이 읽기 쉬운 레이블입니다.

scopes

Array<string> | null

키를 다음 항목으로 제한합니다 scopes. 아래의 세 가지 상태를 참조하세요. 고급 API 키가 필요합니다.

folderIds

Array<string>

키를 다음 프로젝트 폴더로 제한합니다. 고급 API 키가 필요합니다.

custom_metadata

Map<string, string>

최대 20개의 키/값 쌍(키는 100자 이하, 값은 500자 이하). 고급 API 키가 필요합니다.

protected

불리언

키를 다음 상태로 생성합니다: protected 상태.

scopes 생성 시:

생략됨 - 새 키는 호출 자격 증명 자체의 범위를 상속합니다 ("나와 같은 키를 생성"). 이는 요금제와 무관합니다: 전체 액세스 키는 전체 액세스 키를 생성하고, 범위가 지정된 키는 동일한 범위를 가진 키를 생성하며, 폴더도 같은 방식으로 상속됩니다. 다음을 생략하는 스크립트는 scopes 워크스페이스에 고급 API 키 기능이 있든 없든 동일하게 동작합니다.
null - 명시적인 전체 액세스 (범위 미지정) 키. 호출자 자신도 전체 액세스 권한을 가져야 합니다(범위가 지정된 호출자는 거부됩니다 - 참조: 하위집합 규칙).
[] (빈 배열) - 유효한 키이지만 능력이 없습니다; 모든 범위 지정 경로에서 거부됩니다. 나중에 범위를 부여할 자리표시자로 유용합니다.
["model:infer", …] - 범위 지정된 해당 능력으로만 제한됩니다( 섹션 이름 예: 모델 해당 섹션의 모든 범위를 부여합니다).
["role:reviewer", …] - 역할 프리셋: 생성 시 해당 역할의 범위로 확장됩니다. 내장 역할(라벨러, 검토자, 소유자) 또는 사용자 지정 역할의 이름을 사용하세요; role:owner 는 전체 액세스를 의미합니다. 명시적 범위와 함께 조합할 수 있습니다.

명시적인 scopes 배열 ([], 목록 또는 role: 프리셋), folderIds또는 custom_metadata 다음이 필요합니다: 고급 API 키 요금제 기능(그렇지 않으면 403). 생략하면 scopes (상속) 및 null (전체)는 그렇지 않습니다 - 따라서 기본값은 모든 요금제에서 작동합니다.

요청 예시

curl --location 'https://api.roboflow.com/<workspace_id>/api-keys?api_key=$ROBOFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "name": "production-server",
    "scopes": ["model:infer"]
}'

응답

{
  "keyId": "9f8c1a2b3d4e5f60",
  "key": "AbCdEf0123456789xyz",
  "name": "production-server",
  "scopes": ["model:infer"],
  "folderIds": [],
  "protected": false,
  "publishableKey": "rf_<workspace_id>"
}

호출자는 키를 생성할 수 있지만 보유한 것 이상의 범위/폴더를 부여하도록 요청했거나, 워크스페이스 요금제에 요청한 고급 기능이 포함되어 있지 않습니다. 본문: {"error": "string"}.

자격 증명에 다음이 없습니다: api-key:create 범위가 없거나, 속하지 않는 워크스페이스를 대상으로 합니다. 본문: {"error": {"message", "type", "hint"}}로 구성됩니다. 오류.

해당 키 필드가 비밀 값이며 오직 이 응답에 표시됩니다. 지금 저장하세요; 다시는 가져올 수 없습니다.

API 키 업데이트

PATCH /:workspace/api-keys/:keyId

키의 이름, 범위 또는 메타데이터를 업데이트하고, 키를 보호하거나, 활성화/비활성화합니다.

헤더

이름

값

Content-Type

application/json

본문 (변경하려는 필드만 보내세요)

이름

유형

설명

필수

name

문자열

새 표시 이름.

scopes

Array<string> | null

새 scopes (호출자의 하위집합). 아래의 세 가지 상태를 참조하세요. 고급 API 키가 필요합니다.

custom_metadata

Map<string, string>

키의 메타데이터를 대체합니다. 고급 API 키가 필요합니다.

protected

true

키를 보호합니다. API는 보호 해제를 할 수 없습니다 - 아래를 참조하세요.

비활성화됨

불리언

비활성화(true) 또는 다시 활성화(false) 키. 고급 API 키가 필요합니다.

다음의 세 가지 상태: scopes (PATCH 의미론은 생성과 약간 다릅니다 - 필드를 생략하면 변경되지 않은 채로 유지됩니다):

생략됨 - 키의 기존 범위는 변경되지 않습니다.
null - 키가 전체 액세스 (범위 미지정). 이를 부여하려면 호출자 자신이 전체 액세스를 보유해야 합니다.
[] (빈 배열) - 키는 유효한 자격 증명을 유지하지만 능력이 없습니다.
["model:infer", …] - 대체합니다 키의 범위를 정확히 이 집합으로 ( 섹션 이름 해당 섹션의 모든 범위로 확장됩니다).

전송하면 scopes (포함하여 [] 또는 null), custom_metadata또는 비활성화됨 다음이 필요합니다: 고급 API 키 요금제 기능.

요청 예시

curl --location --request PATCH 'https://api.roboflow.com/<workspace_id>/api-keys/<key_id>?api_key=$ROBOFLOW_API_KEY' \
--header 'Content-Type: application/json' \
--data '{ "name": "renamed-key" }'

응답

{ "apiKey": { "keyId": "9f8c1a2b3d4e5f60", "name": "renamed-key", "prefix": "abcd", "scopes": ["model:infer"], "folderIds": [], "default": false, "protected": false, "disabled": false } }

다음과 같이 보내면 반환됩니다 "protected": false (API는 키의 보호를 해제할 수 없으며), 또는 호출자가 부여할 수 없는 범위를 요청한 경우. 본문: {"error": "string"}.

해당 keyId 워크스페이스 내에 존재합니다(본문: {"error": "string"}), 또는 자격 증명에 다음이 없습니다: api-key:update 범위가 없거나 / 속하지 않는 워크스페이스를 대상으로 합니다(본문: {"error": {"message", "type", "hint"}}). 참조: 오류.

현재 다음 상태인 키를 비활성화하려고 하면 반환됩니다 protected.

API 키 철회

DELETE /:workspace/api-keys/:keyId

키를 철회(영구 비활성화)합니다. 이를 사용하는 기존 애플리케이션은 즉시 인증에 실패합니다.

요청 예시

curl --location --request DELETE 'https://api.roboflow.com/<workspace_id>/api-keys/<key_id>?api_key=$ROBOFLOW_API_KEY'

응답

{ "status": "revoked", "keyId": "9f8c1a2b3d4e5f60" }

키는 protected. 먼저 Roboflow 대시보드에서 보호를 해제하세요.

키 보호

하나의 protected 키는 API, CLI, MCP 서버, 또는 대시보드에서도 보호가 해제되기 전까지 비활성화하거나 철회할 수 없습니다. 이를 사용해 자동화 에이전트가 실수로 프로덕션 키를 중단하지 못하게 하세요.

보호: PATCH 에서 { "protected": true }.
보호 해제: 할 수 있습니다 오직 다음에서 수행할 수 있습니다: 대시보드. API/CLI/MCP는 의도적으로 키의 보호를 해제할 수 없으므로, 손상되었거나 지나치게 성급한 에이전트가 안전장치를 제거한 뒤 한 번에 키를 철회하는 것을 막습니다.

공개 키

모든 워크스페이스에는 공개용 키 다음 형식의 rf_<workspaceId>. 그것은:

비밀이 아님 - 클라이언트 측 / 브라우저 코드에 포함해도 안전함(예: inferencejs).
추론 + 모델 다운로드만 가능 - 데이터 관리, 학습, 키 관리는 할 수 없습니다.
영구적 - 워크스페이스 ID에서 파생되므로 생성, 순환(로테이션), 철회할 수 없습니다.

다음에서 읽으세요: publishableKey 목록/생성 응답의 필드에서, 또는 직접:

GET /:workspace/api-keys/publishable

curl --location 'https://api.roboflow.com/<workspace_id>/api-keys/publishable?api_key=$ROBOFLOW_API_KEY'
# { "publishableKey": "rf_<workspace_id>" }

브라우저/엣지 추론에는 공개용 키를, 서버 측 작업에는 범위가 지정된 개인 키를 사용하세요. 공개용 키를 가진 사람은 누구나 해당 워크스페이스의 모델에 대해 추론을 실행하고(및) 다운로드할 수 있다는 점에 유의하세요. 이것이 "공개용" 자격 증명의 의도된 트레이드오프입니다.

권한 하위집합 규칙

권한 상승을 방지하기 위해, 새로 생성되거나 업데이트된 키는 이를 만드는 자격 증명보다 더 많은 능력을 가질 수 없습니다:

이 엔드포인트를 다음과 함께 호출하면 범위가 지정된 개인 키, 새 키의 scopes 는 호출 키의 범위의 하위집합이어야 하며, 그 folderIds 는 호출 키의 폴더의 하위집합이어야 합니다. 범위가 지정되지 않은(전체 액세스) 키는 무엇이든 부여할 수 있습니다.
다음을 사용해 호출하면 사용자를 대신하는 OAuth 토큰일 때사용자를 대신하는 OAuth 토큰

, 요청된 범위는 해당 사용자의 역할과도 추가로 비교됩니다 - 역할이 허용하는 능력만 부여할 수 있습니다. 403.

오류

상태

의미

오류 형식

400

잘못된 요청 본문(예: 알 수 없는 범위, 형식이 잘못된 메타데이터).

{"error": "string"}

403

호출자는 경로에 대해 승인되었지만 다음을 요청했습니다: 보유한 것 이상의 능력을 부여 (호출자의 범위/폴더를 초과하는 경우), 요금제에 고급 API 키가 없거나, API를 통해 보호 해제를 시도한 경우.

{"error": "string"}

404

해당 keyId 키가 워크스페이스에 존재하지 않거나, 또는 자격 증명에 경로가 요구하는 범위가 없거나, 또는 키가 속하지 않은 워크스페이스를 대상으로 합니다. Roboflow는 리소스 존재 여부를 의도적으로 숨깁니다.

{"error": {"message", "type", "hint"}} 권한/워크스페이스 사례에는; {"error": "string"} 알 수 없는 경우에는 keyId.

409

키가 보호되어 있어 비활성화/철회할 수 없습니다.

{"error": "string"}

두 가지 오류 본문 형식. 대부분의 엔드포인트는 문자열 오류 - {"error": "Some message"}. 대신 인증/권한 계층은 객체 - {"error": {"message": "…", "type": "…", "hint": "…"}} (권한/잘못된 워크스페이스의 경우 404 위의 내용과, 누락되었거나 잘못된 키의 경우 401). 처리할 소비자를 작성하세요 둘 다 형식.

흔한 함정: 자격 증명에 단순히 해당 경로의 범위가 없는 요청은 반환됩니다 404, 아니라 403. 한 403 는 호출이 는 키를 관리할 권한은 있지만, 호출자가 가진 것보다 더 많은 권한을 넘겨주려 했습니다.

다음을 참조하세요 오류 및 상태 코드 일반 오류 형식은

CLI

해당 roboflow api-key 명령 그룹을 사용하면 터미널에서 작업 공간의 API 키를 관리할 수 있습니다. 이는 다음을 래핑합니다 API 키 REST 엔드포인트 그리고 CLI 구성의 작업 공간과 자격 증명을 사용합니다(참조 CLI 설치 및 설정).

전체 비밀 값은 표시됩니다 오직 키를 만들 때 표시됩니다. 즉시 저장하세요 - list/get에서는 다시는 표시되지 않습니다.

roboflow api-key --help

명령

설명

list

작업 공간의 API 키를 나열합니다.

get

키 하나의 세부 정보를 표시합니다.

생성

새 키를 만듭니다(비밀 값은 한 번만 출력됩니다).

업데이트

키의 이름, 범위 또는 메타데이터를 업데이트합니다.

protect

키를 보호됨으로 표시합니다.

disable

키를 비활성화하거나 다시 활성화합니다.

철회

키를 영구적으로 폐기합니다.

공개용

작업 공간의 공개 가능한 키를 출력합니다.

추가 --json (전역 플래그로, 명령 앞에 붙여) 스크립팅용 기계 판독 가능한 출력을 얻으세요. 예: roboflow --json api-key list.

키 나열

roboflow api-key list
roboflow api-key list --include-disabled --include-folders

키 하나 가져오기

키는 해당 keyId (에 표시되는 비밀이 아닌 식별자 list):

roboflow api-key get <key_id>

키 만들기

# 호출 자격 증명의 범위를 상속합니다(호출자가 전체 액세스이면 전체 액세스 키)
roboflow api-key create "my-app"

# 범위가 지정된 키(--scope를 반복; 고급 API 키 필요)
roboflow api-key create "inference-only" --scope model:infer

# 역할 프리셋 - RBAC 역할의 범위(내장 또는 사용자 지정 역할 이름)를 부여합니다;
# 명시적 범위와 조합할 수 있습니다. role:owner는 전체 액세스를 의미합니다.
roboflow api-key create "reviewer-bot" --scope role:reviewer --scope model:infer

# 폴더 범위 지정 + 보호됨
roboflow api-key create "edge-device" --folder <folder_id> --protected

# 메타데이터 첨부(--metadata를 반복; 고급 API 키 필요)
roboflow api-key create "ci-key" --metadata team=vision --metadata env=prod

비밀 값은 한 번만 출력됩니다. 스크립트에서 캡처하려면 다음을 사용하세요 --json 그리고 다음으로 파이프하세요 jq:

roboflow --json api-key create "ci-key" | jq -r .key > .env.key

--scope, --folder이며, --metadata 고급 API 키 플랜 기능이 필요하며, 명령을 실행하는 자격 증명이 이미 가진 권한만 부여할 수 있습니다.

키 업데이트

# 이름 변경
roboflow api-key update <key_id> --name "renamed-key"

# 키의 범위를 교체합니다(--scope를 반복)
roboflow api-key update <key_id> --scope model:infer --scope project:read

# 키의 메타데이터를 교체합니다(--metadata를 반복)
roboflow api-key update <key_id> --metadata team=vision --metadata env=prod

--scope 대체합니다 키의 기존 범위를 입력한 집합과 정확히 동일한 것으로 바꾸고, --metadata 키의 메타데이터를 교체합니다. 다음을 보내세요 --name 하나도 건드리지 않고 이름만 변경하려면 단독으로 사용하세요.

범위나 메타데이터를 변경하려면 고급 API 키 플랜 기능이 필요합니다(다음을 사용한 이름 변경은 --name 필요하지 않습니다). 생성, 명령을 실행하는 자격 증명이 이미 보유한 범위만 부여할 수 있습니다.

키 보호 / 보호 해제

roboflow api-key protect <key_id>

보호된 키는 CLI, API 또는 MCP를 통해 비활성화하거나 폐기할 수 없습니다. 보호 해제는 다음에서만 할 수 있습니다 대시보드 - 의도적으로 다음은 없습니다 unprotect 명령이 없으므로, 자동화된 워크플로에서는 안전장치를 제거하고 운영 키를 한 번에 폐기할 수 없습니다.

키 비활성화 / 다시 활성화

roboflow api-key disable <key_id>            # 비활성화
roboflow api-key disable <key_id> --enable   # 다시 활성화

비활성화된 키는 API에서 거부되지만 다시 활성화할 수 있습니다. 보호된 키는 비활성화할 수 없습니다.

roboflow api-key disable (그리고 다음으로 다시 활성화하는 것은 --enable)에는 다음이 필요합니다 고급 API 키 플랜 기능, 범위 지정 생성 에서 --scope/--folder. 이는 다음과 일치합니다 REST API.

키 폐기

roboflow api-key revoke <key_id>          # 확인을 요청합니다
roboflow api-key revoke <key_id> --yes    # 프롬프트를 건너뜁니다(스크립트용)

폐기는 영구적입니다. 보호된 키는 CLI에서 폐기할 수 없습니다 - 먼저 대시보드에서 보호를 해제하세요.

공개 가능한 키 가져오기

roboflow api-key publishable
roboflow --json api-key publishable | jq -r .publishableKey

공개 가능한 키(rf_<workspaceId>)는 비밀이 아니며 브라우저 / inferencejs 코드에 포함해도 안전합니다. 이는 추론 전용이며 생성하거나 폐기할 수 없습니다. 참조 공개 키 를 참조하세요.

이전Roboflow API 키 찾기 다음OAuth 2.1 (Roboflow로 로그인)

마지막 업데이트 11일 전

도움이 되었나요?