인증 코드 생성¶
POST /api/v1/offline_token/temporary_auth_code/create
개요¶
현재 워크스페이스에 단기 일회성 인증 코드를 생성하여, 프런트엔드에서 임시 오프라인 액세스 Token으로 교환할 수 있도록 합니다.
호출 전 및 사용 단계¶
expires와 선택적 roles를 제출합니다. API는 authCode를 반환하며 Token을 직접 반환하지 않습니다. code는 그대로 동일 사이트의 프런트엔드 인증 진입점으로 전달하고, 프런트엔드 서비스의 GET /api/v1/auth-token/get?authCode=...에서 교환합니다. 또한 콘솔의 기존 연동 규칙에 따라 /redirect_auth/{authCode}?overwrite=true&to=xxx를 열 수 있습니다. 중간 페이지에서 code를 소비하며, overwrite=true는 현재 로그인 상태를 덮어쓰고, 생략하면 임시 사용을 위한 것입니다. to는 URL 인코딩된 사이트 내 상대 주소입니다. 콘솔 도메인과 프런트엔드 API 도메인은 동일 사이트 접속 주소에 따라 선택해야 합니다. 교환에 성공하면 code는 즉시 삭제되어 재사용할 수 없습니다. 동시 교환 및 철회 시 하나의 흐름만 code를 소비할 수 있습니다. authCode를 DF-API-KEY, X-FT-Auth-Token 또는 오프라인 Token으로 간주하여 비즈니스 API를 직접 호출해서는 안 됩니다. expires는 액세스 Token의 신청 수명으로, 단위는 초이며, 만료 시각은 code 생성 시점부터 계산됩니다. 교환해도 다시 계산되지 않습니다. 실제 값은 요청 값과 사이트 Token 상한 중 더 작은 값으로 결정됩니다. code 자체의 expiresIn은 기본 600초이며 사이트 구성에 따라 결정되고, expires와 다릅니다. Token 신청 수명이 먼저 만료되면 code 캐시가 남아 있어도 교환할 수 없습니다. 역할 목록은 먼저 현재 워크스페이스의 역할로 각 항목을 확인해야 합니다. code 생성은 각 역할을 완전히 검증하지 않으며, 대상 액세스 권한을 보유함을 증명하지도 않습니다. 역할 권한은 교환으로 Token을 생성할 때 계산 및 캐시되며, 이후 권한 변경이 이미 발급된 Token에 자동 반영된다고 보장하지 않습니다. 사용하지 않은 code는 일회성 인증 코드 철회를 호출하여 철회할 수 있습니다. 교환 후 Token의 유효 기간과 철회 경계는 아래 내용을 참조하세요.
요청 헤더¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>가져오기 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 가져옵니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| expires | integer | Y | 필수 액세스 Token 신청 수명으로, 1~604800초이며 실제로는 사이트 상한 제약도 받습니다. code 생성 시점부터 계산되며 code 자체 TTL을 제어하지 않습니다. null 허용: False $maxValue: 604800 $minValue: 1 예: 3600가져오기 또는 입력 방법: 실제 액세스 작업에 따라 초 단위를 선택합니다. 예를 들어 3600은 1시간입니다. 짧은 작업에는 짧은 수명을 설정하는 것이 좋습니다. |
| roles | array | 선택적 역할 UUID 배열입니다. 생략하거나 []로 두면 기본적으로 shared 공유 액세스 ID가 되며, 기본 readOnly가 아닙니다. 현재 각 역할의 유효성을 강하게 검증하지 않으므로 클라이언트가 먼저 확인해야 합니다. null 허용: False 예: ["readOnly"]가져오기 또는 입력 방법: 역할 목록의 content.data[].uuid에서 동일 워크스페이스의 대상 역할을 가져옵니다. 예: wsAdmin/general/readOnly 또는 role_사용자 지정 역할. 최소 액세스 요구 사항에 따라 선택합니다. |
|
| roles[*] | string | 조건부 필수 | 단일 non-null 역할 식별자 문자열입니다. null 허용: False 예: readOnly가져오기 또는 입력 방법: 역할 목록에서 단일 역할 UUID를 복사하고 표시 이름을 입력하지 마세요. |
파라미터 추가 설명¶
후속 교환은 프런트엔드 서비스에서 처리합니다: GET <FrontEndpoint>/api/v1/auth-token/get?authCode=<생성 시 반환된 authCode>. 성공 후 content에는 token, tokenType=custom, workspaceUUID, expiresAt(Unix 초)가 포함되며, expiresAt은 최종 액세스 마감 시각입니다. 이 교환 응답은 본 생성 API에 속하지 않습니다. 교환 실패 시 400 ft.NotFoundAuthCode, 401 ft.OfflineTokenExpired 또는 워크스페이스 오류가 발생할 수 있습니다. code 만료 또는 철회는 아직 교환되지 않은 code에만 영향을 주며, 이전에 교환된 Token을 철회하지 않습니다. 현재 기존 Token 철회 API는 신버전 Token에 호환성 제한이 있으므로 후속 페이지 설명에 따라 확인하세요.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/offline_token/temporary_auth_code/create' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"roles":["readOnly"],"expires":3600}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content.authCode | string | 일회성 인증 코드로, 동일 사이트 프런트엔드 인증 교환 진입점에 그대로 전달해야 합니다. 분해하거나 직접 조합하지 마세요. |
| content.action | string | 고정 값 offline_custom_token으로, custom 오프라인 Token으로 교환 가능한 일회성 code임을 나타냅니다. |
| content.workspaceUUID | string | API Key가 속한 워크스페이스 UUID이며, 이후 액세스 범위이기도 합니다. |
| content.expiresIn | integer | code 자체의 유효 기간으로 단위는 초이며 기본값은 600입니다. 최종 Token의 액세스 수명이 아닙니다. |
| content.declaration | object 또는 null | 워크스페이스 공용 선언입니다. |
{
"code": 200,
"content": {
"authCode": "AUTH-CODE-EXAMPLE.1785430800",
"action": "offline_custom_token",
"workspaceUUID": "wksp_example",
"expiresIn": 600,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
역할이 유효하지 않더라도 생성 시 역할이 존재하지 않는다는 오류가 반환된다고 보장하지 않습니다. 생성 성공 후에도 교환 결과와 대상 화면의 권한 검사를 통해 실제 액세스를 검증해야 합니다. 현재 API Key 워크스페이스에만 적용되며, 단일 리소스 허용 목록 파라미터는 제공되지 않습니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방식 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 타입 및 값을 확인하세요. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하세요. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 단일 JSON 객체를 제출하세요. |
| 401 | ft.WKSPNotExistOrReleased | 생성 시 실시간 검사에서 워크스페이스가 삭제 또는 해제된 것으로 확인됨 | 워크스페이스가 존재하지 않음/또는 해제됨 | API Key가 속한 워크스페이스가 유효한지 확인하세요. |
| 500 | ft.InternalServerError | 캐시 또는 기타 내부 처리 실패 | 내부 오류 | traceId를 보관하고 관리자에게 연락하여 결과를 확인하세요. 자동으로 권한 부여를 반복하거나 오류를 근거로 철회가 완료되었다고 판단하지 마세요. |