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

# 개발자 시작하기

> 체커블 OAuth2 API로 서비스를 연동해보세요

## 🎯 체커블 OAuth2 API란?

체커블 OAuth2 API는 여러분이 만드는 앱에서 OAuth2 인증을 통해 체커블과 연동을 하고, 챌린지 목록을 조회하고, 특정 챌린지에 인증을 업로드할 수 있게 해주는 API입니다.

### 전체 플로우

1. **OAuth2 인증**: 앱에서 체커블 OAuth2 인증을 통해 사용자 인증
2. **챌린지 조회**: 사용자가 참여 중인 챌린지 목록 조회
3. **인증 업로드**: 특정 챌린지에 메시지와 이미지로 인증 업로드

### 주요 기능

* **OAuth2 인증**: 표준 OAuth2 프로토콜을 통한 안전한 인증
* **사용자 정보**: OAuth2 토큰을 통한 사용자 정보 조회
* **챌린지 조회**: 사용자가 참여 중인 챌린지 목록 조회
* **인증 업로드**: 챌린지에 메시지와 이미지로 인증 업로드

### 사용 시나리오

* **피트니스 앱**: 운동 완료 후 체커블 챌린지에 자동 인증
* **학습 앱**: 공부 시간 기록 후 체커블 챌린지에 자동 인증
* **생산성 앱**: 목표 달성 후 체커블 챌린지에 자동 인증

## 📋 사전 준비사항

### OAuth2 클라이언트 발급

* [Checkable 서비스 개발자 지원팀](mailto:dev@checkable.app)에 OAuth2 클라이언트 발급 요청
* 발급받은 클라이언트 정보 확인

## 🔐 OAuth2 인증 플로우

### 1. Authorize - 인증 코드 요청

앱에서 사용자를 체커블 OAuth2 인증 페이지로 리다이렉트:

```
https://checkable.app/auth/member/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=all&state=YOUR_STATE
```

### 2. Code - 인증 코드 수신

사용자가 체커블에 로그인하고 앱에 권한을 부여하면, 인증 코드가 포함된 URL로 리다이렉트됩니다:

```
YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=YOUR_STATE
```

### 3. Token - 액세스 토큰 교환

인증 코드를 액세스 토큰으로 교환:

```http theme={null}
POST /api/auth/member/oauth2/token HTTP/1.1
Host: checkable.app
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
client_id=YOUR_CLIENT_ID&
code=AUTHORIZATION_CODE&
redirect_uri=YOUR_REDIRECT_URI
```

**응답:**

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token_expires_in": 2592000,
  "scope": "all"
}
```

## 📊 API 활용 예시

### 1. 사용자 정보 조회

액세스 토큰을 사용하여 사용자 정보를 조회합니다:

```http theme={null}
GET /api/auth/member/oauth2/me HTTP/1.1
Host: checkable.app
Authorization: Bearer ACCESS_TOKEN
```

**응답:**

```json theme={null}
{
  "member": {
    "id": 123,
    "name": "discord_username",
    "email": "user@example.com"
  }
}
```

### 2. 챌린지 목록 조회

사용자가 참여 중인 챌린지 목록을 조회합니다:

```http theme={null}
POST /api/public/challenges HTTP/1.1
Host: checkable.app
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
```

**응답:**

```json theme={null}
{
  "challenges": [
    {
      "uuid": "challenge-uuid",
      "title": "챌린지 제목",
      "guildName": "디스코드 서버명",
      "channelName": "채널명",
      "discordChannelId": "123456789",
      "discordMessageId": "987654321"
    }
  ]
}
```

### 3. 인증 업로드

특정 챌린지에 인증을 업로드합니다:

```http theme={null}
POST /api/public/challenges/{challengeUuid}/upload-message HTTP/1.1
Host: checkable.app
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "message": "오늘 운동 완료!",
  "imageData": "base64-encoded-image-data"
}
```

**응답:**

```json theme={null}
{
  "messageId": "discord-message-id"
}
```

## 🔒 보안 고려사항

1. **토큰 보안**: OAuth2 액세스 토큰은 안전하게 보관하고 정기적으로 갱신
2. **HTTPS 사용**: 모든 API 통신은 HTTPS를 통해 이루어져야 함
3. **토큰 범위**: 필요한 최소한의 권한만 요청
4. **입력 검증**: 모든 입력 데이터는 적절히 검증

## 📞 지원

### 기술 지원

* **이메일**: [dev@checkable.app](mailto:dev@checkable.app)
* **Discord**: [체커블 개발자 커뮤니티](https://discord.gg/x8Qtt2aasJ)

### 다음 단계

* [OAuth2 인증 가이드](/developer/oauth2)
* [OAuth2 스펙](/developer/spec/oauth2)
* [API 스펙](/developer/spec/public-api)