---
title: API 키
description: 대시보드에서 API 키를 만들고 권한, 계좌 범위, 만료를 정하는 방법과 재발급, 요청 기록, 안전하게 보관하는 방법을 설명해요.
sidebar:
icon: key-round
---
API를 호출하려면 API 키가 필요해요. API 키는 워크스페이스 하나에 속하고, 키로 보낸 요청은 그 워크스페이스의 주문, 입금, 현금영수증만 다뤄요. 요청에 키를 넣는 방법은 [API 개요의 인증](/api-reference#인증)을 참고하세요.
API 키를 만들고 관리하려면 소유자나 개발자 역할이 필요해요. 만들 수 있는 키 수는 [요금제](/plans)마다 달라요.
파트너 서비스에 워크스페이스 접근을 허용할 때는 API 키를 건네지 말고 [연결된 앱](/connected-apps)으로 연결하세요.
## 키 만들기
대시보드 **API 키**에서 **키 만들기**를 눌러요.
| 항목 | 설명 |
| --- | --- |
| **이름** | 키를 구분할 이름이에요. 2~16자로 입력해요. 예: `쇼핑몰 서버` |
| **권한** | **읽기·쓰기** 또는 **읽기 전용** 중에서 골라요. 아래 [권한](#권한)을 참고하세요. |
| **계좌 범위** | **모든 계좌**는 나중에 추가하는 계좌도 포함해요. **고른 계좌만**은 고른 계좌의 입금과 주문만 다뤄요. 아래 [계좌 범위](#계좌-범위)를 참고하세요. |
| **만료** | 만료 없음, 30일 뒤, 90일 뒤, 1년 뒤, 날짜 지정 중에서 골라요. 날짜를 지정하면 그날 23:59까지 쓸 수 있어요. |
API 키는 `sk_live_`로 시작해요. 페이싱크에는 테스트용 키가 따로 없어서, 모든 키가 실제 계좌의 주문과 입금을 다뤄요.
:::warning
API 키 값은 만든 직후 한 번만 보여요. **저장했어요**를 누르기 전에 안전한 곳에 복사해 두세요.
:::
키를 만든 직후
## 권한
| 권한 | 할 수 있는 일 |
| --- | --- |
| 읽기·쓰기 | 주문을 만들고, 바꾸고, 결제 완료 처리하고, 취소해요. 현금영수증을 발급하고 취소해요. 조회도 모두 할 수 있어요. |
| 읽기 전용 | 주문, 입금, 현금영수증 조회만 해요. 쓰기 요청은 `403`, `290007`로 실패해요. |
주문 현황을 보여 주는 내부 도구나 정산 배치처럼 조회만 하는 곳에는 읽기 전용 키를 쓰세요.
## 계좌 범위
**고른 계좌만**으로 만든 키는 고른 계좌로 받는 주문과 그 계좌로 들어온 입금만 다뤄요. 매장이나 지점마다 서버가 따로 있을 때, 서버마다 자기 계좌의 키를 주면 다른 매장의 주문을 건드리지 못해요.
- 주문을 만들 때 `bankAccountIds`에 고른 계좌만 넣을 수 있고, 모든 계좌로 받는 주문은 만들 수 없어요.
- 범위 밖의 주문이나 입금에 접근하면 `403`, `80002`가 와요.
- 현금영수증은 계좌와 관계가 없어서 제한하지 않아요.
API별 동작은 [API 키 계좌 범위](/api-reference#api-키-계좌-제한)를 참고하세요. 주문의 받을 계좌와의 차이는 [다중 계좌 라우팅](/multi-bank-account-routing#api-키의-접근-가능한-계좌-와는-어떻게-다른가요)에 정리해 뒀어요.
## 재발급, 끄기, 삭제
키 목록의 행 메뉴에서 관리해요.
| 작업 | 하는 일 |
| --- | --- |
| **재발급** | 새 키 값을 만들어요. 이름, 권한, 계좌 범위, 만료는 그대로이고 이전 키는 바로 멈춰요. |
| **수정** > **키 사용** 끄기 | 이 키로 보낸 요청을 모두 거절해요. 다시 켜면 같은 키 값으로 쓸 수 있어요. |
| **삭제** | 키를 지워요. 이 키로 보낸 요청은 바로 거절하고, 되돌릴 수 없어요. |
재발급하면 이전 키를 잠시 함께 쓰는 기간이 없어요. 새 키를 서버에 넣을 준비를 한 뒤에 재발급하세요. 멈춘 키, 꺼진 키, 지운 키, 만료된 키로 보낸 요청은 `401`, `290006`으로 실패해요.
## 요청 기록
API 키 화면의 **요청 기록**에서 최근 30일 동안 키로 보낸 요청의 시각, 경로, 결과, 응답 시간을 확인할 수 있어요. 키와 결과(성공, 오류)로 걸러 볼 수 있어요. 연동 중에 어떤 요청이 실패했는지 찾을 때 쓰세요.
## 키 보관
- 키는 서버 환경변수나 비밀 관리 도구에 넣고, 코드 저장소에 올리지 마세요.
- 브라우저나 모바일 앱에 키를 넣지 마세요. 사용자가 키를 꺼내 주문을 마음대로 만들 수 있어요. API는 항상 내 서버에서 호출하세요.
- 서버나 용도마다 키를 따로 만들면 하나가 유출돼도 그 키만 재발급하면 돼요.