본문으로 건너뛰기

Authentication

모든 요청은 API Key를 bearer token으로 보내 인증합니다. 이 페이지는 키가 무엇이고 무엇을 담을 수 있으며 수명을 어떻게 관리하는지를 다룹니다.

Authorization: Bearer replace-with-your-api-key

키가 대표하는 것​

키는 특정 계정을 대신해 발급되며 그 계정으로 행위합니다. 키의 역할과 tenant는 발급 요청으로 받지 않고 서버가 대상 계정을 조회해 채웁니다. 여기서 세 가지가 따라옵니다.

  • 키는 계정의 역할을 물려받으므로, 관리자 계정으로 발급한 키는 관리자 키입니다.
  • 키는 계정의 tenant에 묶이며, 계정이 비활성화되면 키도 동작하지 않습니다.
  • 역할을 검사하는 endpoint는 키에 저장된 값이 아니라 계정의 역할을 검사합니다.

키 자체는 영숫자 32자입니다. 전체 값은 발급 또는 재발급 응답에서 딱 한 번만 반환됩니다. 이후 조회에서는 앞 8자와 뒤 4자만 보이는 maskedApiKey만 제공됩니다.

발급 시점에 키를 확보합니다

이후에는 전체 값을 되찾을 방법이 없습니다. 잃어버렸다면 되읽으려 하지 말고 재발급합니다. 재발급하면 이전 값은 무효가 됩니다.

tenant 결속​

관리자와 사용자 키는 발급받은 tenant의 도메인에서만 인증됩니다. 다른 tenant의 도메인으로 호출하면 알 수 없는 키와 동일하게 API_KEY_004로 실패합니다.

슈퍼 관리자 키는 tenant가 없어서 - tenantSeq가 null입니다 - 어느 tenant의 도메인에서도 인증됩니다.

Scope​

scope 값은 네 가지입니다.

Scope허용 범위
api:read외부 API 읽기
api:write외부 API 쓰기
mcp:readMCP 읽기
mcp:writeMCP 쓰기

자유롭게 조합할 수 없습니다. 발급 가능한 조합은 두 가지뿐입니다.

Allowed scope combinations
["api:read", "mcp:read"]
["api:read", "api:write", "mcp:read", "mcp:write"]

그 밖의 조합은 각 값이 개별적으로 유효하더라도 API_KEY_010으로 거부됩니다. scopes는 대상 계정의 역할과 무관하게 모든 발급 요청에 필수이며, 빈 배열은 REQUEST_001로 검증에서 걸립니다.

scope는 신뢰할 수 있는 권한 경계가 아님

두 조합 모두 api:read를 포함하므로 모든 키가 공통 scope 게이트를 통과합니다. 그리고 여러 endpoint 그룹이 그 이후로는 scope를 검사하지 않습니다. admins와 super-admin 트리 전체, 그리고 users, notifications, config, web-office, pinned-folders, API Key 관리 endpoint가 그렇습니다. 따라서 읽기 전용 키로도 이들에서 쓰기 동작을 수행할 수 있습니다. scope는 강제되는 제약이 아니라 의도를 나타내는 표시로 보고, 접근 통제는 누가 어떤 키를 갖는지로 합니다.

세 가지 관리 경로​

누구의 키를 관리하느냐에 따라 사용할 endpoint가 달라집니다.

Base 경로관리 대상필요한 역할
/api/external/v1/users/api-keys호출 계정이 본인용으로 발급한 키scope 게이트 외에 없음
/api/external/v1/admins/api-keys호출자 tenant의 ADMIN·USER 키ADMIN
/api/external/v1/super-admin/api-keys모든 tenant의 모든 키SUPER_ADMIN

세 경로 모두 목록, 발급, 만료일 변경, 재발급, 활성화, 비활성화의 여섯 가지 동작을 제공합니다.

누가 누구의 키를 발급할 수 있는가​

모든 경우에 규칙은 같습니다. 본인 또는 더 낮은 권한의 계정에 대해서만 발급할 수 있고, 같은 권한의 계정에는 발급할 수 없습니다.

경로대상규칙
사용자항상 호출 계정userSeq를 지정할 수 없음
관리자본인 또는 같은 tenant의 USER다른 ADMIN은 API_KEY_012로 거부. 다른 tenant의 계정은 존재하지 않는 경우와 동일하게 USER_005
슈퍼 관리자본인 또는 지정한 tenant의 ADMIN·USER다른 SUPER_ADMIN은 API_KEY_012로 거부

슈퍼 관리자 경로에서는 대상이 관리자나 사용자이면 tenantSeq가 필수이고, 본인용으로 발급할 때는 보내면 안 됩니다. 생략하면 API_KEY_007, 대상의 tenant와 다르면 API_KEY_006, 슈퍼 관리자 키에 지정하면 API_KEY_011을 반환합니다. 검증은 대상 계정, tenant, scope 순서로 진행되므로 가장 앞에서 걸린 조건이 응답됩니다.

슈퍼 관리자는 관리자 경로로 발급할 수 없음

POST /admins/api-keys는 역할 게이트 자체는 슈퍼 관리자 키를 통과시키지만, 호출 계정이 슈퍼 관리자이면 API_KEY_013으로 거부합니다. 슈퍼 관리자 경로를 사용합니다. 이 가드는 발급에만 있으며, 나머지 다섯 개의 관리자 키 동작은 슈퍼 관리자 호출자를 받아들입니다.

사용자 경로는 호출자와 같은 권한의 키를 만들어 냄

POST /users/api-keys는 호출자 제한 없이 호출 계정 자격으로 키를 발급합니다. 관리자 키로 호출하면 또 다른 관리자 키가, 슈퍼 관리자 키로 호출하면 또 다른 슈퍼 관리자 키가 만들어집니다. 따라서 유출된 키로 같은 권한의 키를 더 만들어 둘 수 있고, 그 키들은 원래 키를 폐기해도 살아남습니다. 유출이 의심되면 알고 있는 키 하나가 아니라 해당 계정의 키 목록을 조회해 전부 폐기합니다.

키 발급​

POST /api/external/v1/users/api-keys
POST /api/external/v1/admins/api-keys
POST /api/external/v1/super-admin/api-keys
파라미터Type필수설명
keyNamestringYes키 이름, 최대 100자
keyPurposestringYes키 용도, 최대 255자
expireDatestringYesISO-8601 지역 일시로 된 만료 시각. 미래여야 함
scopesarrayYes허용된 두 조합 중 하나
userSeqintegerNo발급 대상 계정. 관리자·슈퍼 관리자 경로 전용
tenantSeqinteger조건부대상 tenant. 슈퍼 관리자 경로 전용
Issue a key
curl -X POST "https://drive.example.com/api/external/v1/admins/api-keys" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"keyName": "Reporting job", "keyPurpose": "Nightly file inventory", "expireDate": "2027-04-02T23:59:59", "scopes": ["api:read", "mcp:read"]}'
Issue response
{
  "result": true,
  "code": 201,
  "message": "Created",
  "data": {
    "apiKey": "0Kf3XqN7bT2wYh5RmA8dLpV1cZ6sE4gJ"
  }
}
키는 반드시 만료됨

무기한 키는 없습니다. expireDate는 필수이며 미래 시각이어야 합니다. 지정한 날짜 전에 교체 계획을 세웁니다.

키 목록​

GET /api/external/v1/users/api-keys
GET /api/external/v1/admins/api-keys
GET /api/external/v1/super-admin/api-keys
파라미터Type필수설명
psintegerYes페이지 크기, 최소 1
cilongNocursor - 이전 페이지의 마지막 apiKeySeq
tsintegerNo특정 tenant로 한정. 슈퍼 관리자 경로 전용

결과는 apiKeySeq 내림차순입니다. pageSize와 hasNext는 항상 반환되고, nextCursor는 다음 페이지가 있을 때만 나타납니다. hasNext는 페이지가 가득 찼을 때 true가 되므로, 마지막 페이지가 정확히 ps만큼이면 다음 페이지가 있다고 보고한 뒤 그 페이지가 비어 있게 됩니다.

FieldType의미
apiKeySeqinteger키 식별자이자 페이지네이션 cursor
keyNamestring발급 시 지정한 이름
keyPurposestring명시한 용도
maskedApiKeystring키의 앞 8자와 뒤 4자
scopesarray키가 가진 scope
statusstringACTIVE 또는 INACTIVE
expireDatestring만료 시각
isExpiredboolean만료 시각이 지났는지 여부
lastUsedDatestring마지막으로 인증된 요청 시각. 사용 이력이 없으면 null
registerDatestring키 발급 시각

관리자와 슈퍼 관리자 목록은 대상 계정을 userSeq, userId, userName, roleType으로 함께 알려주고, 슈퍼 관리자 목록에는 tenantSeq와 tenantName이 추가됩니다. 사용자 목록은 본인 키만 반환하므로 이 값들이 없습니다.

만료된 키도 목록에 남습니다. 슈퍼 관리자 목록에 ts를 주면 tenant에 속하지 않는 슈퍼 관리자 키는 결과에서 빠집니다.

사용자 경로는 본인이 발급한 키만 보여줌

관리자가 대신 발급해 준 키는 발급자가 관리자이므로 여기에 나타나지 않고 여기서 폐기할 수도 없습니다. 지금 인증에 쓰고 있는 키가 관리자 발급 키라면, 그 키는 이 경로로 스스로를 관리할 수 없습니다.

만료일 변경​

PATCH /api/external/v1/users/api-keys/{apiKeySeq}/expire-date
PATCH /api/external/v1/admins/api-keys/{apiKeySeq}/expire-date
PATCH /api/external/v1/super-admin/api-keys/{apiKeySeq}/expire-date
파라미터Type필수설명
expireDatestringYesISO-8601 지역 일시로 된 새 만료 시각. 미래여야 함

이미 만료된 키도 미래 날짜로 연장하면 다시 사용할 수 있습니다.

키 교체​

POST /api/external/v1/users/api-keys/{apiKeySeq}/reissue
POST /api/external/v1/admins/api-keys/{apiKeySeq}/reissue
POST /api/external/v1/super-admin/api-keys/{apiKeySeq}/reissue

같은 기록에 대해 새 키 값을 만들고 상태를 ACTIVE로 되돌립니다. 응답에 새 값이 전체로 담기며, 이전 값은 즉시 동작을 멈춥니다.

호출에 쓰고 있는 키를 교체하면 그 credential이 끊김

응답이 만들어지는 순간부터 이전 값은 무효입니다. 다음 요청을 보내기 전에 새 값을 저장합니다.

중지와 복구​

PATCH /api/external/v1/users/api-keys/{apiKeySeq}/deactivate
PATCH /api/external/v1/users/api-keys/{apiKeySeq}/activate

같은 두 경로가 관리자와 슈퍼 관리자 경로에도 있습니다. 유출이 의심될 때 가장 빠른 대응은 비활성화입니다. 키는 즉시 API_KEY_004로 인증에 실패하며, 활성화하면 복구됩니다. 되돌릴 수 없게 하려면 비활성화 대신 재발급해서 유출된 값이 다시 살아날 수 없게 합니다.

에러​

API_KEY_004와 HTTP 401은 모든 인증 실패를 포괄합니다. 헤더 누락, 알 수 없는 값, 비활성화된 키, 만료된 키, 계정이 비활성화된 키, 잘못된 tenant 도메인에서의 사용이 모두 여기에 해당하며 응답으로는 구분되지 않습니다.

API_KEY_001과 HTTP 404는 다룰 수 없는 키를 포괄합니다. 존재하지 않는 키와 호출 중인 경로의 범위 밖에 있는 키가 모두 같은 응답입니다. 다른 사람의 키를 탐색하지 못하게 하려는 의도입니다.

REQUEST_001은 요청 값 검증 실패이며, message에 고정 문구가 아니라 걸린 필드 목록이 담깁니다. AUTH_009는 호출한 키가 역할 또는 scope 게이트를 통과하지 못했다는 뜻입니다.

전체 목록은 Errors를 참고합니다.