Token 폐기(구 인터페이스)¶
POST /api/v1/offline_token/temporary_token/revoke
개요¶
구 흐름에서 임시 오프라인 Token 캐시를 취소합니다. 현재 버전에는 신규 Token 형식 호환 제한이 존재합니다.
호출 전 및 사용 단계¶
이것은 구 인터페이스이며, 기존 문서는 2026-05-31에 내려갈 예정입니다. 현재 소스 코드는 여전히 유지되고 있으나, 배포 사이트에서의 공개 여부는 실제 버전을 기준으로 합니다. 신규 통합에서는 일회성 authCode 생성/교환 흐름을 사용합니다. 호환성이 확인된 구 custom. 접두사이면서 구 서명 방식으로 파싱할 수 있는 Token만 캐시 삭제 단계까지 진행됩니다. 현재 공개 라우트는 Token 유형을 전달하지 않으므로, 접두사가 없는 신규 RS256 Token에 대해서는 성공적인 취소를 보장할 수 없으며 일반적인 내부 오류가 반환될 수 있습니다. 재시도하면 성공할 것이라고 가정하거나 다른 형식으로 임의 변환하여 취소 확인을 대체해서는 안 됩니다. 호환 형식에 대해 성공적으로 true를 반환하면 해당 Token의 이 워크스페이스 내 오프라인 인증 캐시를 삭제하며, 이후 사용 시에는 재검증이 필요하고 무효화되어야 합니다. 이미 시작되었거나 완료된 요청은 이로 인해 철회되지 않습니다. 캐시가 더 이상 존재하지 않아도 호환 Token은 여전히 true를 반환할 수 있습니다. 교환되지 않은 code는 일회성 인증 코드 취소를 사용하십시오. 단, code가 이미 교환된 후 code를 취소해도 Token에는 영향을 주지 않습니다. 단기 액세스가 필요한 경우 생성 시 expires를 제어하고 최종 expiresAt에 따라 만료 시점을 확인하십시오.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| token | string | Y | 취소할 전체 Token 문자열이며 필수입니다. authCode가 아닙니다. 신규 버전의 접두사 없는 Token은 현재 취소 호환 제한이 있습니다. null 허용: False 예시: custom.<LEGACY-HS256-JWT>획득 또는 입력 방법: 구 흐름에서 보유한 임시 customToken에서 그대로 가져옵니다. 이 예시는 자리 표시자일 뿐이므로 자신의 대상 Token으로 교체하십시오. 먼저 대상이 현재 워크스페이스에 속하는지 및 이 인터페이스가 호환하는 구 형식인지 확인하십시오. |
파라미터 추가 설명¶
현재 실패 경로가 항상 401 OfflineTokenFailed를 안정적으로 반환하지는 않습니다. 일부 파싱 실패, 워크스페이스 불일치 또는 인식되지 않는 접두사 상황에서는 500 InternalServerError가 반환됩니다. 이 페이지는 실제 경로를 기준으로 설명하며, 소스 코드 주석의 “신구 Token 호환”을 검증된 동작으로 간주하지 않습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/offline_token/temporary_token/revoke' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"token":"custom.<LEGACY-HS256-JWT>"}'
응답¶
HTTP 200, application/json. 아래 예시는 직접 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | boolean | 호환 파싱이 완료되고 캐시 삭제 흐름이 완료된 경우에만 true를 반환합니다. Token 또는 삭제 수량은 반환하지 않습니다. |
{
"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 객체를 제출하십시오. |
| 401 | ft.OfflineTokenFailed | Token이 세 부분으로 된 JWT도 아니고 구 접두사와 JWT를 분리할 수도 없음 | 무로그인 토큰 검증 실패 | authCode 또는 불완전한 문자열을 잘못 전달하지 않았는지 확인하십시오. 접두사를 임의로 추가하지 마십시오. |
| 500 | ft.InternalServerError | 신규 버전의 접두사 없는 Token 서명 검증 호환 실패, 또는 Token 파싱/워크스페이스 불일치/접두사 미지원 경로가 현재 예외 처리 결함을 트리거함. 캐시 처리 실패일 수도 있음 | 내부 오류 | 이를 근거로 취소가 성공했다고 판단할 수 없습니다. 대상 형식, 소속 워크스페이스 및 만료 시간을 확인하고 traceId를 보관하여 관리자에게 전달해 확인을 요청하십시오. 현재 버전에서는 호환 경로를 별도로 수정해야 합니다. |