> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 인증

> API 키를 만들고 요청을 인증하세요.

> [!NOTE]
>
> GetQR API는 베타 버전이며 일부 워크스페이스에서만 사용할 수 있습니다. 정식 출시 전에 세부 사항이 변경될 수 있습니다.

GetQR API는 모든 요청을 계정 API 키로 인증합니다. 사용자마다 키가 하나씩 있으며, 키는 하나의 워크스페이스에서 사용자 본인으로 동작합니다.

## 시작하기 전에

* 워크스페이스 소유자 또는 편집자여야 합니다. 뷰어는 API 키를 만들거나 사용할 수 없습니다.
* 워크스페이스 소유자의 구독이 활성 상태여야 합니다.

## API 키 만들기

**1. 계정 설정 열기**

계정 설정을 열고 **API**로 이동합니다.

**2. 키 생성**

**Generate API key**를 클릭합니다.

**3. 키 복사**

키를 표시하고 복사합니다. 키는 `sk_live_`로 시작합니다.

키는 언제든지 다시 표시하고 복사할 수 있습니다. 설정에는 키를 만든 시각과 마지막으로 사용한 시각도 표시됩니다.

## 요청 인증

모든 요청의 `Authorization` 헤더에 키를 Bearer 토큰으로 담아 보내세요.

```bash theme={null}
curl "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer sk_live_..."
```

| 문제 | 응답 |
| - | - |
| `Authorization` 헤더가 없음 | `401 unauthorized`: "Missing Authorization header." |
| 헤더가 `Bearer `로 시작하지 않음 | `400 bad_request`: "Misconfigured authorization header. Did you forget to add 'Bearer '?" |
| 알 수 없거나 재생성된 키 | `401 unauthorized`: "Unauthorized: Invalid API key." |
| 역할이 뷰어임 | `403 forbidden`: "API access is not available for this role." |
| 워크스페이스 소유자의 구독이 활성 상태가 아님 | `403 forbidden`: "Access denied: This account does not have an active subscription." |
| 워크스페이스에서 API가 활성화되지 않음 | `404 not_found`: "This endpoint is not available." |

키 없이 작동하는 엔드포인트는 [상태 확인](https://docs.getqr.com/ko/api/endpoints/health.md)뿐입니다.

## 접근 권한 및 역할

* **역할.** API 키는 워크스페이스 소유자와 편집자만 만들고 사용할 수 있습니다. 뷰어는 사용할 수 없습니다.
* **워크스페이스.** 각 키는 하나의 워크스페이스에 속하며, 모든 요청은 해당 워크스페이스에서 실행됩니다. 워크스페이스 ID를 전달할 필요가 없습니다.
* **실시간 확인.** 접근 권한은 요청할 때마다 현재 역할과 워크스페이스 소유자의 구독을 기준으로 확인됩니다. 본인의 구독은 고려되지 않습니다. 역할이 뷰어로 바뀌거나 소유자의 구독이 종료되면, 접근 권한이 복구될 때까지 요청은 `403`을 반환합니다. 새 키는 필요하지 않습니다.
* **제거.** 워크스페이스에서 제거되면 API 키가 삭제됩니다. 다시 추가된 경우 새 키를 생성하세요.

## 키 재생성

키가 유출되었거나 권한이 없는 사람이 키에 접근하게 되었다면 키를 재생성하세요.

> [!WARNING]
>
> 현재 키는 즉시 작동을 멈춥니다. 이 키를 사용하는 앱이나 통합은 새 키로 업데이트할 때까지 작동하지 않습니다.

**1. Regenerate 클릭**

계정 설정에서 **API**로 이동한 다음 **Regenerate**를 클릭합니다.

**2. 확인**

**Regenerate key**를 클릭합니다.

**3. 앱 업데이트**

새 키를 복사하고, 이전 키를 사용하는 모든 곳에서 교체합니다.

## 키를 안전하게 보관하기

키를 비밀번호처럼 다루세요. 키를 가진 사람은 누구나 워크스페이스의 QR 코드를 만들고, 변경하고, 삭제할 수 있습니다.

* 키는 소스 코드가 아니라 환경 변수나 시크릿 관리 도구에 저장하세요.
* API는 서버에서만 호출하세요. 웹사이트, 모바일 앱 등 사용자가 내용을 들여다볼 수 있는 곳에는 절대 키를 넣지 마세요.
* 키는 꼭 필요한 개발자와만 공유하세요.
* 유출이 의심되면 즉시 재생성하세요.

## 자주 발생하는 문제

> [accordion] 이전에 작동하던 키로 401이 반환됩니다
>
> 키가 재생성되었거나, 워크스페이스에서 제거되어 키가 삭제되었습니다. 계정 설정에서 현재 키를 복사하거나 새 키를 생성하세요.

> [accordion] 모든 요청에서 403이 반환됩니다
>
> 역할이 소유자 또는 편집자인지, 워크스페이스 소유자의 구독이 활성 상태인지 확인하세요. 접근 권한이 복구되면 키는 바로 다시 작동합니다.

> [accordion] 404 "This endpoint is not available."가 반환됩니다
>
> API는 베타 버전이며 아직 워크스페이스에서 활성화되지 않았습니다.

> [accordion] API 설정이 보이지 않습니다
>
> API 설정은 워크스페이스 소유자와 편집자에게만, 그리고 API가 활성화된 워크스페이스에서만 표시됩니다.

## 다음 단계

> [card] [API 소개](https://docs.getqr.com/ko/api/introduction.md)

> [card] [오류](https://docs.getqr.com/ko/api/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.