앱의 비공개 자격 증명을 Atoms 클라우드 → 키에 저장하면 해당 값이 Chat 및 소스 코드에 노출되지 않도록 하고, Test 값과 Production 값을 별도로 관리할 수 있습니다.

키를 사용하기 전에 프로젝트를 Atoms 클라우드에 연결하세요. 연결되어 있지 않다면 에이전트에게 Atoms 클라우드 연결을 요청하거나 Atoms 클라우드를 따르세요.

Atoms 클라우드에서 키 사용하기

시작하기 전에

키를 추가하기 전에 다음을 확인하세요:

• 데스크톱 웹에서 Atoms를 사용하고 있습니다.
• 프로젝트가 Atoms 클라우드에 연결되어 있습니다.
• 워크스페이스 소유자입니다. 새 키는 워크스페이스 소유자만 추가할 수 있습니다.

키 또는 New Key를 사용할 수 없다면, 의도한 프로젝트를 열었는지와 해당 프로젝트가 Atoms 클라우드에 연결되어 있는지 확인하세요. New Key를 계속 사용할 수 없다면, 워크스페이스 소유자인지 확인하세요. Atoms에 플랜 또는 사용 가능 여부 메시지가 표시되면, 화면의 안내에 따라 사용 가능 상태를 확인하거나 업그레이드한 후 다시 시도하세요.

Test 키 추가하기

1. 데스크톱 기기에서 프로젝트를 엽니다.
2. App 뷰어 가 있는 동일한 워크스페이스 툴바에서 Atoms 클라우드를 선택합니다.
3. Atoms 클라우드 사이드바에서 키를 선택합니다.
4. Test Keys를 연 다음 In This Project를 선택합니다.
5. New Key를 선택합니다.
6. 필수 필드를 입력합니다:
   • Name: RESEND_API_KEY와 같이 명확한 참조 이름을 입력합니다. 문자, 숫자, 밑줄을 사용하고, 문자 또는 밑줄로 시작하세요.
   • Value: 제공업체가 제공한 자격 증명을 정확히 입력합니다.
   • Description: Used to send account emails처럼 이 키의 용도를 설명합니다. 자격 증명 값은 포함하지 마세요.
7. 다른 프로젝트에서도 이 키를 재사용하려면 Save to Library를 선택합니다.
8. Add를 선택합니다. 키가 저장되면 Atoms에 Key added successfully가 표시됩니다.

Test 키 추가

새 키는 워크스페이스 소유자만 추가할 수 있습니다. 키 추가가 필요하면 워크스페이스 소유자에게 요청하세요.

Chat에서 저장된 키 사용하기

메시지에 값을 직접 입력하는 대신 저장된 키를 참조하세요.

1. 데스크톱 버전의 Atoms에서 프로젝트 Chat을 열고 #를 입력합니다.
2. 키를 선택합니다.
3. 저장된 키를 검색한 다음 해당 이름을 선택합니다.
4. 에이전트에게 이 키의 용도와 연동에서 수행하길 원하는 작업을 설명합니다.

# 메뉴는 저장된 키의 값을 메시지에 삽입하지 않고 해당 키에 대한 참조를 추가합니다.

Chat에서 저장된 키 참조

저장된 키 테스트하기

1. App 뷰어에서 해당 키를 사용하는 간단한 작업을 수행합니다.
2. 테스트 이메일 전송이나 테스트 데이터 반환처럼 예상한 결과가 나오는지 확인합니다.
3. 표시되는 오류나 로그를 검토하고, 키 값이 노출되지 않는지 확인합니다.

서비스에서 테스트 키와 라이브 키를 별도로 제공하는 경우, 앱을 빌드하는 동안에는 테스트 키를 사용하세요. 라이브 키는 앱이 게시된 후에만 사용하세요. 테스트에 실패하면 제공업체의 대시보드에서 키가 활성 상태인지, 요청한 작업을 수행할 권한이 있는지 확인하세요. 문제를 해결할 때는 절대로 키 값을 Chat에 붙여넣지 마세요.

키 작동 방식 이해하기

키를 추가하기 전에 Atoms가 무엇을 저장하는지와 자격 증명을 어떻게 보호해야 하는지 이해하면 도움이 됩니다.

Atoms가 저장하는 항목

Atoms 클라우드 → 키는 앱이 API 키 및 액세스 토큰과 같은 외부 서비스에 연결하는 데 사용하는 자격 증명을 저장합니다.

저장된 각 키에는 이름, 설명, 비공개 값이 있습니다. 이름과 설명은 에이전트가 언제 키를 사용해야 하는지 이해하는 데 도움이 되며, 비공개 값은 Chat에 숨겨진 상태로 유지됩니다.

키를 얻는 위치

Atoms는 외부 서비스용 자격 증명을 생성하거나 제공하지 않습니다. 관련 서비스 제공업체로부터 직접 받아야 합니다. 권한 선택, 키 테스트, 만료 여부 확인 시에는 제공업체의 안내를 따르세요.

비공개 자격 증명을 비밀로 유지하기

비공개 자격 증명을 Chat, 소스 코드, 브라우저에서 실행되는 코드, 스크린샷, 로그 또는 지원 메시지에 절대 붙여넣지 마세요. 키에 저장한 다음 저장된 항목을 이름으로 참조하세요.

비공개 값이 이미 노출되었다면 유출된 것으로 간주하고 제공업체를 통해 폐기하거나 교체하세요.

비공개 자격 증명과 브라우저에 안전한 자격 증명

키는 저장된 값을 Public 또는 Private로 표시하지 않습니다. 값을 키에 저장한다고 해서 브라우저에 노출되는 코드에서 자동으로 안전하게 사용할 수 있게 되는 것은 아닙니다. 앱이 브라우저에서 해당 값을 사용하면 방문자가 이를 확인할 수 있을 수 있습니다.

자격 증명을 어디에 사용할지 결정하기 전에 제공업체 문서를 확인하세요:

• 제공업체가 노출해도 안전하다고 명시한 경우에만 브라우저에 노출되는 코드에서 값을 사용하세요.
• 비공개 자격 증명은 앱 방문자에게 노출되지 않는 서버 측 또는 백엔드 로직에 보관하세요.

키의 환경과 저장 위치 선택하기

키를 추가할 때는 두 가지를 별도로 결정해야 합니다:

• 어떤 환경에서 키를 사용할지
• 키를 이 프로젝트에만 둘지, 다른 프로젝트에서도 사용할 수 있게 할지

환경 선택하기

옵션	사용 시점
Test Keys	App 뷰어에서 앱을 개발하고 테스트하는 동안 사용됩니다. 별도의 Production 값을 추가하지 않으면 게시된 앱도 Test 값을 사용합니다.
Production Keys	게시된 앱에 별도의 라이브 자격 증명이 필요한 경우 사용됩니다. Production 값은 게시 과정에서 추가되며 Test 값과 별도로 관리됩니다.

키를 저장할 위치 선택하기

옵션	사용 시점
In This Project	현재 프로젝트에서만 사용해야 하는 키라면 이 옵션을 선택하세요.
Key Library	여러 프로젝트에서 키를 의도적으로 재사용하려는 경우 이 옵션을 선택하세요. Test 키를 추가하거나 업데이트할 때 라이브러리에서 사용할 수 있게 하려면 Save to Library를 선택하세요.

환경과 저장 위치는 서로 독립적입니다. Test 키를 Key Library에 저장하면 재사용할 수 있게 되지만, 이것이 Production 값으로 바뀌는 것은 아닙니다.

기본적으로 In This Project를 사용하세요. 프로젝트 간 공유가 확실히 필요할 때만 키를 라이브러리에 저장하세요.

별도의 Production 값 사용하기

저장된 키를 사용하는 프로젝트를 게시할 때, 게시 흐름에서 Production Keys 구성을 요청할 수 있습니다. 기본적으로 게시된 앱은 Test 값을 사용합니다. 다른 자격 증명을 사용하려면 Production을 선택하고 해당 키에 대해 별도의 값을 저장하세요.

다음과 같은 경우 별도의 Production 값을 사용하세요:

• 제공업체가 테스트용 자격 증명과 라이브 자격 증명을 다르게 제공하는 경우
• 개발 중 사용한 자격 증명이 게시된 앱에서 사용되지 않기를 원하는 경우

Production 값은 게시 흐름을 통해 생성됩니다. Production Keys 탭에서 New Key를 선택해 생성할 수는 없습니다. 게시된 앱에 대해 Production 값이 구성된 후에는 Atoms 클라우드 → 키 → Production Keys에서 확인할 수 있습니다.

앱을 게시하거나 업데이트한 후에는 게시된 웹사이트에서 관련 사용자 여정을 다시 수행해 Production 키가 올바르게 작동하는지 확인하세요. 전체 배포 과정은 게시 및 배포를 참고하세요.

자격 증명 업데이트 또는 교체하기

저장된 Test 값 업데이트하기

1. Atoms 클라우드 → 키 → Test Keys를 엽니다.
2. 항목이 저장된 위치에 따라 In This Project 또는 Key Library를 엽니다.
3. 키의 Value 또는 Description를 선택하고 업데이트된 정보를 입력한 다음 Update를 선택합니다.
4. Save success가 표시될 때까지 기다린 후 영향을 받는 흐름을 다시 테스트합니다.

계획된 키 교체

기존 자격 증명이 여전히 안전하고 앱 중단 없이 교체하려는 경우 다음 단계를 따르세요:

1. 서비스 제공업체를 통해 대체 자격 증명을 생성합니다.
2. Atoms에서 Test 값을 교체한 다음 App 뷰어에서 영향을 받는 기능을 테스트합니다.
3. 게시된 앱이 별도의 Production 값을 사용한다면 해당 값도 교체하고 업데이트를 게시합니다.
4. 게시된 웹사이트에서 동일한 기능을 테스트합니다.
5. 대체 자격 증명이 올바르게 작동하는 것을 확인한 후 제공업체를 통해 이전 자격 증명을 폐기합니다.

자격 증명이 노출되었을 수 있는 경우

자격 증명이 유출된 것으로 간주하고 즉시 조치하세요:

1. 서비스 제공업체를 통해 해당 자격 증명을 폐기하거나 비활성화합니다.
2. 대체 자격 증명을 생성합니다.
3. Atoms에서 관련 Test 및 Production 값을 업데이트합니다.
4. App 뷰어와 게시된 앱 모두에서 영향을 받는 기능을 다시 테스트합니다.
5. 가능한 경우 소스 코드, Chat, 스크린샷, 로그에서 노출된 복사본을 제거합니다.

키를 삭제하거나 Atoms에서 해당 값을 제거해도 원래 자격 증명이 폐기되지는 않습니다. 반드시 서비스 제공업체를 통해 폐기해야 합니다.

자격 증명 제거하기

저장된 키를 삭제하기 전에 앱이 더 이상 해당 키에 의존하지 않는지 확인하세요:

1. 키를 사용하는 기능을 제거하거나, 해당 참조를 다른 저장된 키로 교체합니다.
2. 원래 자격 증명이 더 이상 사용되지 않도록 서비스 제공업체를 통해 폐기합니다.
3. Atoms 클라우드 → 키를 열고 비활성 항목을 찾은 다음 Delete를 선택하고 확인합니다.

키 삭제는 되돌릴 수 없습니다. 또한 여전히 해당 키를 참조하는 미리보기나 이전 체크포인트가 손상될 수 있습니다. Delete를 사용할 수 없다면 해당 키가 아직 활성 상태로 표시된 것입니다. 다시 시도하기 전에 해당 키에 대한 모든 참조를 제거하거나 교체하세요.

FAQ

내 Test 키는 App Viewer에서는 작동하지만 게시 후에는 작동하지 않습니다. 왜 그런가요?

Test 키가 App Viewer에서는 작동하지만 게시된 앱에서 키가 없거나 비어 있어서 실패하는 경우:

1. 관련 Test 또는 Production 값이 마지막 게시 전과 후 중 언제 저장되었는지 확인하세요. 게시 후에 저장되었다면 변경 사항이 적용되도록 다시 게시하세요.
2. 저장된 키에 올바른 Test 또는 Production 값이 있는지 확인하세요. 별도의 Production 값이 구성되지 않은 경우 게시된 앱은 Test 값을 사용합니다.
3. 단서를 찾기 위해 다운스트림 서비스 오류를 검토하세요. “Unauthorized”는 일반적으로 해당 환경에 대해 키가 비어 있거나 잘못되었음을 의미합니다.

문제가 계속되면 Support에 문의하고 다음을 포함하세요:

• 프로젝트 링크 또는 라이브 URL
• 영향을 받는 키 이름과 문제가 있는 값이 Test인지 Production인지 여부
• 다운스트림 서비스의 전체 오류 내용
• 구성 페이지의 민감 정보가 제거된 스크린샷
• 키 구성이 게시 전과 후 중 언제 저장되었는지 여부

중요: 키 이름만 제공하세요. 비밀 값, 비밀번호 또는 토큰은 보내지 마세요.