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

# OAuth 2.0 개요

> 사용자 동의를 받아 API를 호출하는 인가 모델과 토큰 수명, 사용할 수 있는 권한 범위를 알려드릴게요.

사용자를 대신해 글을 쓰거나 사용자의 정보를 읽으려면 그 사용자의 동의가 필요합니다. 로켓펀치는 OAuth 2.0 **Authorization Code + PKCE** 방식으로 이를 처리합니다.

## 인가 모델 한눈에 보기

| 항목                 | 값                                           |
| ------------------ | ------------------------------------------- |
| 인가 방식              | Authorization Code + PKCE, Refresh Token 회전 |
| 클라이언트 유형           | Confidential만 지원 — 시크릿 키가 반드시 필요합니다         |
| PKCE               | `S256` **필수** — `plain`이나 누락은 거부됩니다         |
| Access Token       | JWT, 기본 수명 15분                              |
| Refresh Token      | `rt_`로 시작하는 문자열, 기본 수명 30일, **쓸 때마다 새로 발급** |
| Authorization Code | 유효 5분, **한 번만** 사용 가능                       |
| 리다이렉트 URI          | 앱당 1개, 글자 단위 정확 일치                          |

## 엔드포인트

주소가 둘로 나뉘어 있습니다. 사용자를 브라우저로 보내는 곳과, 서버끼리 토큰을 주고받는 곳이 다릅니다.

| 단계         | 엔드포인트                                                                    | 호출 주체    |
| ---------- | ------------------------------------------------------------------------ | -------- |
| 사용자 동의     | `https://developers.rocketpunch.com/oauth/authorize`                     | 사용자 브라우저 |
| 토큰 발급 · 갱신 | `https://openapi.rocketpunch.com/oauth/token`                            | 빌더 서버    |
| 토큰 폐기      | `https://openapi.rocketpunch.com/oauth/revoke`                           | 빌더 서버    |
| 사용자 정보 조회  | `https://openapi.rocketpunch.com/oauth/userinfo`                         | 빌더 서버    |
| 메타데이터      | `https://openapi.rocketpunch.com/.well-known/oauth-authorization-server` | 빌더 서버    |

<Warning>
  동의 화면은 개발자 콘솔 주소(`developers.rocketpunch.com`), 토큰 발급은 API 서버 주소(`openapi.rocketpunch.com`)입니다. 자주 혼동되는 부분이니 확인해 주세요.
</Warning>

## 권한 범위(scope)

현재 동의받을 수 있는 권한은 두 가지입니다.

| scope     | 받을 수 있는 것       |
| --------- | --------------- |
| `profile` | 사용자의 이름과 프로필 정보 |
| `email`   | 사용자의 이메일 주소     |

요청한 권한은 **함께 승인되거나 함께 거부**됩니다. 사용자가 일부만 고를 수는 없습니다.

`/oauth/userinfo`로 사용자 정보를 조회하려면 `profile`이 필요하고, 응답에 이메일을 포함하려면 `email`도 함께 받아야 합니다.

<Note>
  현재 추가 권한 동의는 앱 소유자에게만 제공하며, 일반 사용자 지원은 추후 확대할 예정입니다.
</Note>

## 동의 화면이 생략되는 경우

사용자가 이전에 동의한 내역이 아직 유효하고 이번에 요청한 권한을 모두 포함한다면 동의 화면 없이 바로 통과합니다. 다음 경우에는 화면이 다시 표시됩니다.

* 처음 연동하는 사용자일 때
* 이전보다 넓은 권한을 요청할 때
* 동의가 만료됐거나 동의 항목이 변경됐을 때

## 토큰 다루기

Access Token은 15분이면 만료됩니다. 만료되면 Refresh Token으로 새로 발급받으세요.

Refresh Token은 **사용할 때마다 새 값으로 교체**됩니다. 응답으로 받은 새 Refresh Token을 반드시 저장하고, 이전 값은 버리세요. 이전 값을 다시 쓰면 실패합니다.

## 다음 단계

<Card title="OAuth 연동하기" icon="rocket" href="/openapi/auth-oauth-quickstart">
  PKCE 생성부터 토큰 교환, API 호출까지 실제 코드로 안내합니다.
</Card>