인증 code 폐기¶
POST /api/v1/offline_token/temporary_auth_code/revoke
개요¶
현재 워크스페이스에서 아직 교환되지 않은 일회성 custom 인증 코드를 철회합니다.
호출 전 및 사용 단계¶
일회성 인증 코드 생성의 content.authCode 값을 그대로 사용하며, 동일한 워크스페이스에서 권한이 있는 API Key로 제출합니다. 해당 공개 생성 흐름에서 생성된 offline_custom_token code만 철회할 수 있으며, 다른 공유, 스냅샷 또는 반복 교환 가능한 인증 코드에는 사용할 수 없습니다. true가 반환되면 아직 교환되지 않은 code가 삭제되어 더 이상 교환할 수 없습니다. code와 교환 과정은 잠금 내에서 직렬로 처리됩니다. 교환이 먼저 성공한 경우 철회는 code가 존재하지 않는다고 반환하며, 이미 생성된 Token을 소급하여 철회하지는 않습니다. 만료되었거나, 사용되었거나, 이미 철회된 code를 다시 철회하면 NotFoundAuthCode가 발생하며, 멱등적으로 성공하지 않습니다. 현재 동일한 생성자 Key인지 여부는 검증하지 않으며, 주요 경계는 동일한 워크스페이스 및 해당 인터페이스 권한입니다.
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| authCode | string | Y | 필수 일회성 인증 코드입니다. 교환된 Token을 제출하지 말고, 시간 접미사를 임의로 잘라내지 마십시오. null 허용: False 예: AUTH-CODE-EXAMPLE.1785430800획득 또는 입력 방법: 일회성 인증 코드 생성이 반환한 content.authCode를 사용합니다. |
파라미터 추가 설명¶
code를 철회해도 이미 교환된 Token의 접근을 중지할 수 없습니다. 교환 요청이 타임아웃된 경우, 먼저 연동 측에서 Token을 이미 획득했는지 확인하십시오. "철회 시 code를 찾을 수 없음"을 Token이 무효화되었다는 의미로 해석하지 마십시오.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/offline_token/temporary_auth_code/revoke' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"authCode":"AUTH-CODE-EXAMPLE.1785430800"}'
응답¶
HTTP 200, application/json. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content | boolean | 아직 교환되지 않은 code가 성공적으로 삭제되면 true입니다. |
{
"code": 200,
"content": true,
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 타입 및 값을 확인하십시오. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 문법이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하십시오. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 단일 JSON 객체를 제출하십시오. |
| 400 | ft.NotFoundAuthCode | code가 존재하지 않거나, 만료되었거나, 사용되었거나, 본 인터페이스에서 지원하는 일회성 custom code가 아니거나, 동시 처리에서 잠금을 획득하지 못함 | 인증 code를 찾을 수 없음 | 생성 응답의 원본 authCode를 사용했는지 확인하십시오. 이미 교환된 경우 다시 교환하거나 이 code로 철회할 수 없으며, 완료되지 않은 인증은 업무 필요에 따라 다시 생성하십시오. |
| 403 | ft.WorkspaceForbidden | code에 캐시된 워크스페이스가 현재 API Key의 공간과 다름 | 현재 워크스페이스에 대한 접근 권한이 없음 | 해당 code를 발급한 워크스페이스의 Key를 사용하십시오. 공간을 넘어 철회하지 마십시오. |
| 500 | ft.InternalServerError | 캐시 또는 기타 내부 처리 실패 | 내부 오류 | traceId를 보관하고 관리자에게 문의하여 결과를 확인하십시오. 자동으로 인증을 반복하거나 오류에 근거하여 철회가 완료되었다고 판단하지 마십시오. |