Authentication
모든 요청은 API Key를 bearer token으로 보내 인증합니다. 이 페이지에서는 API Key의 동작 방식, 부여할 수 있는 scope, 발급부터 만료까지 키를 관리하는 방법을 설명합니다.
Authorization: Bearer replace-with-your-USER-API-KEY
API Key와 계정
API Key는 특정 계정에 대해 발급되며, 해당 계정의 권한으로 API를 호출합니다. 키의 역할과 tenant는 발급 요청에서 지정하지 않습니다. 서버가 발급 시점에 대상 계정의 값을 가져와 키에 저장합니다. 따라서 다음과 같이 동작합니다.
- 관리자 계정으로 발급한 키는 관리자 키이며, 해당 관리자의 tenant에서만 사용할 수 있습니다.
- 서버는 요청마다 계정 정보(
userSeq,userId,userName)와 활성 여부만 확인합니다. 계정이 비활성화되면 키도 사용할 수 없습니다. /super-admin/**접근 권한을 포함한 역할과 tenant 검사에는 계정의 현재 역할이 아니라 키에 저장된 값을 사용합니다.
API Key는 영문과 숫자로 이루어진 32자 문자열입니다. 전체 값은 발급 또는 재발급 응답에서 한 번만 반환됩니다.
이후 조회에서는 앞 8자와 뒤 4자만 표시되는 maskedApiKey만 제공합니다.
발급 이후에는 전체 값을 다시 조회할 수 없습니다. 키를 분실했다면 재발급하세요. 재발급하면 이전 값은 더 이상 사용할 수 없습니다.
키를 발급한 뒤 계정의 역할을 변경해도 키는 발급 당시의 역할을 유지합니다. 재발급해도 역할은 갱신되지 않습니다. 변경된 역할을 적용하려면 키를 새로 발급하고 이전 키는 비활성화하세요.
tenant 범위
관리자와 사용자 키는 발급받은 tenant의 도메인에서만 인증됩니다. 다른 tenant의 도메인으로 호출하면 등록되지 않은
키와 마찬가지로 API_KEY_004로 실패합니다.
슈퍼 관리자 키는 특정 tenant에 속하지 않으므로(tenantSeq가 null) 모든 tenant의 도메인에서 인증됩니다.
Scope
scope 값은 다음 네 가지입니다.
| Scope | 허용 범위 |
|---|---|
api:read | 외부 API 읽기 |
api:write | 외부 API 쓰기 |
mcp:read | MCP 읽기 |
mcp:write | MCP 쓰기 |
scope는 자유롭게 조합할 수 없으며, 발급할 수 있는 조합은 다음 두 가지입니다.
["api:read", "mcp:read"]
["api:read", "api:write", "mcp:read", "mcp:write"]
다른 조합은 각 값이 유효하더라도 API_KEY_010으로 거부됩니다. scopes는 대상 계정의 역할과 관계없이 모든 발급
요청에 필수이며, 빈 배열을 보내면 REQUEST_001로 실패합니다.
두 조합 모두 api:read를 포함하므로 모든 키가 공통 scope 검사를 통과합니다. 그리고 admins, super-admin 아래의
모든 endpoint와 users, notifications, config, web-office, pinned-folders, API Key 관리 endpoint는 그 이후에
scope를 따로 검사하지 않습니다. 따라서 읽기 전용 키로도 이 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가 필수이며, 본인용으로 발급할 때는
tenantSeq를 보내지 않습니다. tenantSeq를 생략하면 API_KEY_007을, 대상 계정의 tenant와 다르면 API_KEY_006을,
슈퍼 관리자 키 발급에 지정하면 API_KEY_011을 반환합니다. 대상 계정, tenant, scope 순서로 검증하며, 처음 실패한
조건의 오류를 반환합니다.
대상 계정은 ACTIVE 상태여야 합니다. 계정이 없거나 활성 상태가 아니면 USER_005(404)를, tenantSeq에 해당하는
tenant가 없으면 TENANT_001(404)을 반환합니다.
슈퍼 관리자 경로의 발급 오류는 다음과 같습니다.
| 코드 | HTTP | 원인 |
|---|---|---|
API_KEY_006 | 400 | 대상 계정이 tenantSeq의 tenant에 속하지 않음 |
API_KEY_007 | 400 | 관리자·사용자에게 발급하면서 tenantSeq를 생략함 |
API_KEY_010 | 400 | 허용되지 않는 scope 조합 |
API_KEY_011 | 400 | 슈퍼 관리자 키에 tenantSeq를 지정함 |
API_KEY_012 | 403 | 대상이 다른 슈퍼 관리자 |
USER_005 | 404 | 대상 계정이 없거나 활성 상태가 아님 |
TENANT_001 | 404 | tenantSeq에 해당하는 tenant가 없음 |
REQUEST_001 | 400 | 요청 값 검증 실패 |
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 | 필수 | 설명 |
|---|---|---|---|
keyName | string | Yes | 키 이름, 최대 100자 |
keyPurpose | string | Yes | 키 용도, 최대 255자 |
expireDate | string | Yes | 만료 시각. ISO-8601 형식의 로컬 일시이며 현재보다 이후여야 함 |
scopes | array | Yes | 발급할 수 있는 두 조합 중 하나 |
userSeq | integer | No | 발급 대상 계정. 관리자·슈퍼 관리자 경로 전용 |
tenantSeq | integer | 조건부 | 대상 tenant. 슈퍼 관리자 경로 전용 |
curl -X POST "https://drive.example.com/api/external/v1/admins/api-keys" \
-H "Authorization: Bearer replace-with-your-TENANTADMIN-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"]}'
{
"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 | 필수 | 설명 |
|---|---|---|---|
ps | integer | Yes | 페이지 크기, 최소 1 |
ci | long | No | cursor - 이전 페이지의 마지막 apiKeySeq |
ts | integer | No | 조회할 tenant. 슈퍼 관리자 경로 전용 |
결과는 apiKeySeq 내림차순으로 정렬됩니다. pageSize와 hasNext는 항상 반환되며, nextCursor는 다음 페이지가
있을 때만 포함됩니다. hasNext는 현재 페이지의 항목 수가 ps와 같으면 true입니다. 따라서 마지막 페이지의 항목
수가 정확히 ps와 같으면 hasNext가 true로 반환되고, 다음 페이지를 요청하면 빈 목록이 반환됩니다.
| Field | Type | 의미 |
|---|---|---|
apiKeySeq | integer | 키 식별자이자 페이지네이션 cursor |
keyName | string | 발급 시 지정한 이름 |
keyPurpose | string | 발급 시 지정한 용도 |
maskedApiKey | string | 앞 8자와 뒤 4자만 표시한 키 |
scopes | array | 키에 부여된 scope |
status | string | ACTIVE 또는 INACTIVE |
expireDate | string | 만료 시각 |
isExpired | boolean | 만료 시각이 지났는지 여부 |
lastUsedDate | string | 마지막으로 인증된 요청 시각. 사용 이력이 없으면 null |
registerDate | string | 키 발급 시각 |
관리자와 슈퍼 관리자 목록에는 키를 발급받은 계정의 userSeq, userId, userName, roleType이 함께 포함됩니다.
슈퍼 관리자 목록에는 tenantSeq와 tenantName도 포함되며, 슈퍼 관리자 키는 두 값이 null입니다. 사용자 목록은
본인의 키만 반환하므로 이 필드가 없습니다.
만료된 키도 목록에 표시됩니다. 슈퍼 관리자 목록에 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 | 필수 | 설명 |
|---|---|---|---|
expireDate | string | Yes | 새 만료 시각. ISO-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로 변경합니다. 응답에 새 키의 전체 값이 포함되며, 이전 값은 즉시
사용할 수 없게 됩니다. 만료일은 바뀌지 않으므로 만료된 키는 재발급해도 만료일을 변경하기
전까지 API_KEY_004로 인증에 실패합니다.
응답이 반환되는 시점부터 이전 값은 사용할 수 없습니다. 다음 요청을 보내기 전에 새 값을 저장하세요.
비활성화와 활성화
PATCH /api/external/v1/users/api-keys/{apiKeySeq}/deactivate
PATCH /api/external/v1/users/api-keys/{apiKeySeq}/activate
관리자와 슈퍼 관리자 경로에도 같은 두 endpoint가 있습니다. 키 유출이 의심되면 먼저 키를 비활성화하세요.
비활성화한 키는 즉시 API_KEY_004로 인증에 실패하며, 다시 활성화하면 사용할 수 있습니다. 활성화해도 만료일은
바뀌지 않으므로 만료된 키는 만료일을 연장하기 전까지 사용할 수 없습니다. 유출된 값을 다시 사용할 수 없게 하려면
비활성화 대신 재발급하세요.
오류
API_KEY_004(HTTP 401)는 모든 인증 실패에 반환됩니다. 헤더 누락, 등록되지 않은 값, 비활성화된 키, 만료된 키,
비활성화된 계정의 키, 다른 tenant 도메인에서의 사용이 모두 여기에 해당하며, 응답만으로는 원인을 구분할 수 없습니다.
API_KEY_001(HTTP 404)은 요청한 키를 관리할 수 없을 때 반환됩니다. 존재하지 않는 키와 호출한 경로의 관리 범위를
벗어난 키에 같은 응답을 반환해 다른 계정의 키 존재 여부를 알 수 없게 합니다. 만료일 변경, 재발급, 활성화,
비활성화에서 존재하지 않는 apiKeySeq를 지정해도 같은 응답을 반환합니다. 슈퍼 관리자 경로는 모든 tenant의 키를
관리할 수 있습니다.
REQUEST_001은 요청 값 검증 실패이며, message에는 고정 문구 대신 검증에 실패한 필드 목록이 포함됩니다.
AUTH_009는 호출한 키가 역할 또는 scope 검사를 통과하지 못했다는 뜻입니다.
전체 오류 코드는 Errors를 참고하세요.