--- title: "NAVER API HUB 이관 가이드" slug: "apihub-migration" updated: 2026-09-17T09:07:20Z published: 2026-09-17T09:07:20Z canonical: "guide.ncloud-docs.com/apihub-migration" stale: true --- > ## Documentation Index > Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt > Use this file to discover all available pages before exploring further. # NAVER API HUB 이관 가이드 Classic/VPC 환경에서 이용 가능합니다. 이 가이드는 기존 NAVER Developers Center에서 제공하던 API를 NAVER API HUB로 이관하여 사용할 때 확인해야 하는 항목과 변경해야 하는 연동 정보를 안내합니다. 기존 API와 동일한 기능을 NAVER API HUB에서 사용하려면 네이버 클라우드 플랫폼 계정으로 서비스 이용을 신청하고, 신규 Application을 등록한 후 발급된 인증 정보와 API 호출 주소를 서비스 코드에 반영해야 합니다. ## 이관 절차 NAVER Developers Center에서 사용하던 API를 NAVER API HUB로 이관하는 절차는 다음과 같습니다. 1. **이관 전후 비교 및 기존 연동 정보 확인**: 기존 NAVER Developers Center와 NAVER API HUB의 이용 방식 차이를 확인하고, 기존 서비스 코드에서 사용 중인 API 호출 주소, HTTP Method, 요청 헤더, 요청 파라미터를 확인합니다. 2. **NAVER API HUB 이용 신청 및 Application 등록**: 네이버 클라우드 플랫폼 콘솔에서 NAVER API HUB 이용을 신청하고 API 호출에 사용할 Application을 등록합니다. 3. **인증 정보 확인 및 변경**: NAVER API HUB에서 발급된 Client ID와 Client Secret을 확인하고, 기존 인증 정보를 신규 인증 정보로 교체합니다. 4. **API 호출 정보 변경 및 동작 확인**: API 호출 주소와 요청 헤더를 NAVER API HUB 기준으로 변경한 후 정상 호출 여부를 확인합니다. 5. **오류 처리 확인**: 인증 실패, 권한 없음, 필수 파라미터 누락 등 실패 상황에서 반환되는 오류 응답을 확인하고, 기존 서비스의 예외 처리 로직이 정상적으로 동작하는지 확인합니다. 이관을 시작하기 전 기존 서비스 코드에서 다음 항목을 확인해 주십시오. | 확인 항목 | 설명 | | --- | --- | | 사용 API | 기존 서비스에서 사용 중인 API - <예시> 검색 API, 데이터랩 API 등 | | 호출 주소 | 서비스 코드에서 호출 중인 API 엔드포인트를 확인합니다. | | HTTP Method | GET 또는 POST 등 API 호출 방식을 확인합니다. | | 요청 헤더 | 기존 인증 헤더와 인증 정보 사용 방식을 확인합니다. | | 요청 파라미터 | API 호출 시 전달하는 Query String 또는 Request Body 항목을 확인합니다. | ## 1. 이관 전후 비교 및 기존 연동 정보 확인 NAVER Developers Center에서 NAVER API HUB로 이관할 때 확인할 수 있는 주요 화면은 다음과 같습니다. | 화면 예시 | 기존 NAVER Developers Center | NAVER API HUB | | --- | --- | --- | | 서비스 이용 신청 | - | ![NAVER API HUB Subscription 화면](https://cdn.document360.io/6998976f-9d95-4df8-b847-d375892b92c2/Images/Documentation/NAVER%20API%20HUB%20Subscription%20%E1%84%92%E1%85%AA%E1%84%86%E1%85%A7%E1%86%AB.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A50%3A10Z&se=2026-10-26T23%3A50%3A10Z&sr=c&sp=r&sig=%2FD6P0JJkzljlcRcy1FCxznOlXH3A1SOknGRXTW5cIGs%3D) | | API 선택 및 Application 등록 | ![기존 Developers Center 애플리케이션 등록 화면](https://cdn.document360.io/6998976f-9d95-4df8-b847-d375892b92c2/Images/Documentation/%E1%84%80%E1%85%B5%E1%84%8C%E1%85%A9%E1%86%AB%20Developers%20Center%20%E1%84%8B%E1%85%A2%E1%84%91%E1%85%B3%E1%86%AF%E1%84%85%E1%85%B5%E1%84%8F%E1%85%A6%E1%84%8B%E1%85%B5%E1%84%89%E1%85%A7%E1%86%AB%20%E1%84%83%E1%85%B3%E1%86%BC%E1%84%85%E1%85%A9%E1%86%A8%20%E1%84%92%E1%85%AA%E1%84%86%E1%85%A7%E1%86%AB.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A50%3A10Z&se=2026-10-26T23%3A50%3A10Z&sr=c&sp=r&sig=%2FD6P0JJkzljlcRcy1FCxznOlXH3A1SOknGRXTW5cIGs%3D) | ![NAVER API HUB Application 선택 화면](https://cdn.document360.io/6998976f-9d95-4df8-b847-d375892b92c2/Images/Documentation/NAVER%20API%20HUB%20Application%20%E1%84%89%E1%85%A5%E1%86%AB%E1%84%90%E1%85%A2%E1%86%A8%20%E1%84%92%E1%85%AA%E1%84%86%E1%85%A7%E1%86%AB.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A50%3A10Z&se=2026-10-26T23%3A50%3A10Z&sr=c&sp=r&sig=%2FD6P0JJkzljlcRcy1FCxznOlXH3A1SOknGRXTW5cIGs%3D) | | Application 정보 입력 | ![기존 Developer Center 사용 API 및 WEB 환경 설정 예시](https://cdn.document360.io/6998976f-9d95-4df8-b847-d375892b92c2/Images/Documentation/%E1%84%80%E1%85%B5%E1%84%8C%E1%85%A9%E1%86%AB%20Developer%20Center%20%E1%84%89%E1%85%A1%E1%84%8B%E1%85%AD%E1%86%BC%20API%20%E1%84%86%E1%85%B5%E1%86%BE%20WEB%20%E1%84%92%E1%85%AA%E1%86%AB%E1%84%80%E1%85%A7%E1%86%BC%20%E1%84%89%E1%85%A5%E1%86%AF%E1%84%8C%E1%85%A5%E1%86%BC%20%E1%84%8B%E1%85%A8%E1%84%89%E1%85%B5.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A50%3A10Z&se=2026-10-26T23%3A50%3A10Z&sr=c&sp=r&sig=%2FD6P0JJkzljlcRcy1FCxznOlXH3A1SOknGRXTW5cIGs%3D) | ![NAVER API HUB 정보 입력 화면](https://cdn.document360.io/6998976f-9d95-4df8-b847-d375892b92c2/Images/Documentation/NAVER%20API%20HUB%20%E1%84%8C%E1%85%A5%E1%86%BC%E1%84%87%E1%85%A9%20%E1%84%8B%E1%85%B5%E1%86%B8%E1%84%85%E1%85%A7%E1%86%A8%20%E1%84%92%E1%85%AA%E1%84%86%E1%85%A7%E1%86%AB.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A50%3A10Z&se=2026-10-26T23%3A50%3A10Z&sr=c&sp=r&sig=%2FD6P0JJkzljlcRcy1FCxznOlXH3A1SOknGRXTW5cIGs%3D) | | 인증 정보 확인 | ![기존 Developers Center 애플리케이션 정보 화면](https://cdn.document360.io/6998976f-9d95-4df8-b847-d375892b92c2/Images/Documentation/%E1%84%80%E1%85%B5%E1%84%8C%E1%85%A9%E1%86%AB%20Developers%20Center%20%E1%84%8B%E1%85%A2%E1%84%91%E1%85%B3%E1%86%AF%E1%84%85%E1%85%B5%E1%84%8F%E1%85%A6%E1%84%8B%E1%85%B5%E1%84%89%E1%85%A7%E1%86%AB%20%E1%84%8C%E1%85%A5%E1%86%BC%E1%84%87%E1%85%A9%20%E1%84%92%E1%85%AA%E1%84%86%E1%85%A7%E1%86%AB.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A50%3A10Z&se=2026-10-26T23%3A50%3A10Z&sr=c&sp=r&sig=%2FD6P0JJkzljlcRcy1FCxznOlXH3A1SOknGRXTW5cIGs%3D) | ![NAVER API HUB 인증 정보 화면](https://cdn.document360.io/6998976f-9d95-4df8-b847-d375892b92c2/Images/Documentation/NAVER%20API%20HUB%20%E1%84%8B%E1%85%B5%E1%86%AB%E1%84%8C%E1%85%B3%E1%86%BC%20%E1%84%8C%E1%85%A5%E1%86%BC%E1%84%87%E1%85%A9%20%E1%84%92%E1%85%AA%E1%84%86%E1%85%A7%E1%86%AB.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A50%3A10Z&se=2026-10-26T23%3A50%3A10Z&sr=c&sp=r&sig=%2FD6P0JJkzljlcRcy1FCxznOlXH3A1SOknGRXTW5cIGs%3D) | | API 호출 결과 확인 | ![기존 Developers Center API 호출 결과](https://cdn.document360.io/6998976f-9d95-4df8-b847-d375892b92c2/Images/Documentation/%E1%84%80%E1%85%B5%E1%84%8C%E1%85%A9%E1%86%AB%20Developers%20Center%20API%20%E1%84%92%E1%85%A9%E1%84%8E%E1%85%AE%E1%86%AF%20%E1%84%80%E1%85%A7%E1%86%AF%E1%84%80%E1%85%AA.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A50%3A10Z&se=2026-10-26T23%3A50%3A10Z&sr=c&sp=r&sig=%2FD6P0JJkzljlcRcy1FCxznOlXH3A1SOknGRXTW5cIGs%3D) | ![NAVER API HUB API 호출 결과](https://cdn.document360.io/6998976f-9d95-4df8-b847-d375892b92c2/Images/Documentation/NAVER%20API%20HUB%20API%20%E1%84%92%E1%85%A9%E1%84%8E%E1%85%AE%E1%86%AF%20%E1%84%80%E1%85%A7%E1%86%AF%E1%84%80%E1%85%AA.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A50%3A10Z&se=2026-10-26T23%3A50%3A10Z&sr=c&sp=r&sig=%2FD6P0JJkzljlcRcy1FCxznOlXH3A1SOknGRXTW5cIGs%3D) | ## 2. NAVER API HUB 이용 신청 및 Application 등록 NAVER API HUB를 사용하려면 네이버 클라우드 플랫폼 콘솔에서 서비스 이용을 신청하고, API 호출에 사용할 Application을 등록해야 합니다. 이용 신청 및 Application 등록 절차는 다음과 같습니다. 1. 네이버 클라우드 플랫폼 콘솔에 접속해 주십시오. 2. **Menu** > **All Services** > **Application Services** > **NAVER API HUB** > **신청하기** 메뉴를 차례대로 클릭해 주십시오. 3. **Subscription** 메뉴에서 **[서비스 이용 신청]** 버튼을 클릭해 주십시오. 4. 이용 약관 및 개인정보 제공 안내를 확인한 후 이용 신청을 완료해 주십시오. 5. **Application** 메뉴에서 **[Application 등록]** 버튼을 클릭해 주십시오. 6. 사용할 API를 선택한 후 **[다음]** 버튼을 클릭해 주십시오. 7. Application 이름을 입력한 후 등록을 완료해 주십시오. 참고 - NAVER API HUB에서는 하나의 Application에 여러 API를 등록할 수 있습니다. - 다만 API별 호출 주소와 요청 파라미터는 다르므로, 서비스 코드에서는 API별 호출 로직을 분리하여 구현해야 합니다. ## 3. 인증 정보 확인 및 변경 Application 등록을 완료하면 API 호출에 필요한 인증 정보가 생성됩니다. 기존 NAVER Developers Center에서 사용하던 인증 정보는 NAVER API HUB 호출에 사용할 수 없으므로, NAVER API HUB에서 신규 발급된 Client ID와 Client Secret을 서비스 코드에 반영해야 합니다. 인증 정보 변경 시 확인해야 하는 항목은 다음과 같습니다. | 변경 항목 | NAVER Developers Center | NAVER API HUB | 변경 내용 | | --- | --- | --- | --- | | Client ID | 기존 Application의 Client ID | NAVER API HUB Application의 Client ID | 새로 발급된 Client ID로 교체 | | Client Secret | 기존 Application의 Client Secret | NAVER API HUB Application의 Client Secret | 새로 발급된 Client Secret으로 교체 | | Client ID 요청 헤더 | `X-Naver-Client-Id` | `X-NCP-APIGW-API-KEY-ID` | 요청 헤더명을 NAVER API HUB 기준으로 변경 | | Client Secret 요청 헤더 | `X-Naver-Client-Secret` | `X-NCP-APIGW-API-KEY` | 요청 헤더명을 NAVER API HUB 기준으로 변경 | | 인증 정보 적용 위치 | 서비스 코드 또는 환경 변수 | 서비스 코드 또는 환경 변수 | 기존 인증 정보 사용 위치 확인 후 신규 인증 정보로 변경 | 인증 정보 확인 절차는 다음과 같습니다. 1. **NAVER API HUB** 메뉴에서 **Application**을 클릭해 주십시오. 2. Application Management 화면에서 등록한 Application을 선택해 주십시오. 3. **[인증 정보]** 버튼을 클릭해 주십시오. 4. Client ID와 Client Secret을 확인해 주십시오. 5. 확인한 값을 서비스 코드 또는 환경 변수에 반영해 주십시오. 다음 이미지는 NAVER API HUB에서 인증 정보를 확인하는 화면 예시입니다. ![NAVER API HUB 인증 정보 화면](https://cdn.document360.io/6998976f-9d95-4df8-b847-d375892b92c2/Images/Documentation/NAVER%20API%20HUB%20%E1%84%8B%E1%85%B5%E1%86%AB%E1%84%8C%E1%85%B3%E1%86%BC%20%E1%84%8C%E1%85%A5%E1%86%BC%E1%84%87%E1%85%A9%20%E1%84%92%E1%85%AA%E1%84%86%E1%85%A7%E1%86%AB.png?sv=2026-02-06&spr=https&st=2026-10-26T22%3A50%3A10Z&se=2026-10-26T23%3A50%3A10Z&sr=c&sp=r&sig=%2FD6P0JJkzljlcRcy1FCxznOlXH3A1SOknGRXTW5cIGs%3D) 주의 - 기존 NAVER Developers Center에서 사용하던 Client ID와 Client Secret은 NAVER API HUB 호출에 사용할 수 없습니다. ## 4. API 호출 정보 변경 및 동작 확인 인증 정보를 확인한 후 기존 서비스 코드의 API 호출 주소와 요청 헤더를 NAVER API HUB 기준으로 변경합니다. API 호출 정보 변경 시에는 호출 주소, 요청 헤더, 요청 파라미터, 정상 응답 형식을 함께 확인해야 합니다. ### 호출 정보 변경 예시 | 확인 항목 | NAVER Developers Center | NAVER API HUB | 변경 내용 | | --- | --- | --- | --- | | 호출 도메인 | `https://openapi.naver.com` | `https://naverapihub.apigw.ntruss.com` | NAVER API HUB 호출 도메인으로 변경합니다. | | API Path | `/v1/search/news.json` | `/search/v1/news` | NAVER API HUB 개발 가이드에 명시된 API Path로 변경합니다. | | HTTP Method | `GET` | `GET` | API별 개발 가이드 기준으로 확인합니다. | | Query String | `query={QUERY}&display=5` | `query={QUERY}&display=5` | API 개발 가이드와 실제 호출 결과를 기준으로 동일하게 사용할 수 있는지 확인합니다. | | Client ID 헤더 | `X-Naver-Client-Id` | `X-NCP-APIGW-API-KEY-ID` | NAVER API HUB 인증 헤더명으로 변경합니다. | | Client Secret 헤더 | `X-Naver-Client-Secret` | `X-NCP-APIGW-API-KEY` | NAVER API HUB 인증 헤더명으로 변경합니다. | 변경 전후 호출 예시는 다음과 같습니다. ``` # NAVER Developers Center curl -X GET "https://openapi.naver.com/v1/search/news.json?query={QUERY}&display=5" \ -H "X-Naver-Client-Id: {DEVELOPERS_CLIENT_ID}" \ -H "X-Naver-Client-Secret: {DEVELOPERS_CLIENT_SECRET}" # NAVER API HUB curl -X GET "https://naverapihub.apigw.ntruss.com/search/v1/news?query={QUERY}&display=5" \ -H "X-NCP-APIGW-API-KEY-ID: {API_HUB_CLIENT_ID}" \ -H "X-NCP-APIGW-API-KEY: {API_HUB_CLIENT_SECRET}" ``` 참고 - 위 예시는 뉴스 검색 API 기준입니다. - API별 호출 주소, HTTP Method, 요청 파라미터는 각 API 개발 가이드를 참조해 주십시오. ### 동작 확인 API 호출 정보를 변경한 후 정상 응답이 반환되는지 확인합니다. HTTP 상태 코드, 응답 형식, 서비스 코드에서 사용하는 주요 응답 필드를 중심으로 확인해 주십시오. | 확인 항목 | 변경 여부 | 확인 내용 | | --- | --- | --- | | HTTP 상태 코드 | 정상 호출 기준 변경 없음 | 정상 호출 시 `200 OK`가 반환되는지 확인합니다. | | 응답 Body 구조 | API별 확인 필요 | 기존 서비스 코드에서 사용하던 주요 응답 필드가 동일하게 반환되는지 확인합니다. | | 주요 응답 필드 | API별 확인 필요 | 예: `items`, `title`, `link`, `description` 등 서비스 코드에서 사용하는 필드를 확인합니다. | | 응답 파싱 로직 | API별 확인 필요 | 기존 응답 파싱 로직을 그대로 사용할 수 있는지 확인합니다. | | 응답 Header | 변경 가능 | API Gateway 관련 응답 헤더가 추가되거나 변경될 수 있습니다. 서비스 코드에서 응답 헤더를 사용하는 경우 확인이 필요합니다. | 참고 - 응답 구조는 API별로 다를 수 있으므로 실제 호출 결과와 API 개발 가이드를 기준으로 확인해 주십시오. - 특히 서비스 코드에서 특정 응답 필드나 오류 코드를 기준으로 분기 처리하고 있다면, 이관 후 동일하게 동작하는지 별도로 확인해야 합니다. ## 5. 오류 처리 확인 이관 후 기존 서비스의 예외 처리 로직이 정상적으로 동작하는지 확인하려면 API 호출 실패 상황에서 반환되는 오류 응답을 확인해 주십시오. 확인할 수 있는 오류 케이스는 다음과 같습니다. | 오류 케이스 | 확인 내용 | | --- | --- | | 인증 헤더 누락 | 인증 헤더 없이 호출했을 때 반환되는 오류 응답을 확인합니다. | | 잘못된 인증 정보 | 유효하지 않은 Client ID 또는 Client Secret을 전달했을 때 반환되는 오류 응답을 확인합니다. | | 잘못된 호출 주소 | 존재하지 않는 API Path로 호출했을 때 반환되는 오류 응답을 확인합니다. | | 필수 파라미터 누락 | 필수 요청 파라미터를 누락했을 때 반환되는 오류 응답을 확인합니다. | | 지원하지 않는 API 호출 | 제공되지 않는 API를 호출했을 때 반환되는 오류 응답을 확인합니다. | 주의 - NAVER API HUB는 API Gateway 기반으로 제공되므로 기존 NAVER Developers Center와 오류 응답 형식 또는 상태 코드가 다를 수 있습니다. - 기존 서비스에서 오류 코드 기반 분기 처리를 하고 있다면 이관 후 오류 응답을 별도로 확인해 주십시오. ## 관련 가이드 NAVER API HUB 사용 시 참조할 수 있는 가이드는 다음과 같습니다. - [NAVER API HUB 사용](https://guide.ncloud-docs.com/release-20260917/docs/apihub-use) - [NAVER API HUB 권한 관리](https://guide.ncloud-docs.com/release-20260917/docs/apihub-subaccount) - [NAVER API HUB 리소스 관리](https://guide.ncloud-docs.com/release-20260917/docs/apihub-resource) - [API 가이드 개요](https://api.ncloud-docs.com/docs/naver-api-hub-overview)