회원 API
회원 가입·이메일 인증·로그인·토큰 갱신·내 정보·탈퇴 엔드포인트의 요청, 응답, 에러 코드를 설명합니다.
내 서비스의 최종 사용자(회원)를 위한 인증 API입니다. Project에서 회원 기능을 켜야 동작합니다.
https://api.onttle.com/v1/{projectId}
인증 방법
회원 API는 API Key를 Authorization이 아니라 X-Onttle-Key 헤더로 보냅니다. Authorization 헤더는 로그인한 회원의 access 토큰에 씁니다.
| 자격 증명 | 전달 | 용도 |
|---|---|---|
게시용 키 pk-proj_… |
X-Onttle-Key 헤더 |
브라우저·앱. /auth/*, /me를 호출할 수 있습니다 |
| 회원 access 토큰 | Authorization: Bearer {accessToken} |
로그인한 회원 (/me, /auth/logout, 권한 규칙이 걸린 Table) |
시크릿 키 sk-proj_… |
X-Onttle-Key 헤더 |
서버 전용. Table 권한 규칙과 관계없이 항상 허용됩니다 |
curl https://api.onttle.com/v1/{projectId}/me \
-H "X-Onttle-Key: $ONTTLE_PUBLISHABLE_KEY" \
-H "Authorization: Bearer $ACCESS_TOKEN"
게시용 키는 원래 GET 전용이지만 /auth/*와 /me에서는 POST·PATCH·PUT·DELETE도 허용됩니다. 쿠키 모드에서는 Authorization 대신 쿠키를 쓰며, 회원 문서의 쿠키 모드를 참고하세요.
엔드포인트 요약
| 메서드 | 경로 | 인증 | 설명 |
|---|---|---|---|
POST |
/auth/signup |
게시용 키 | 가입 요청, 인증 메일 발송 (회원은 인증 대기) |
POST |
/auth/email/verify |
게시용 키 | 인증 토큰 확인 → 활성, 크레딧 차감 |
POST |
/auth/email/resend |
게시용 키 | 인증 메일 재발송 |
POST |
/auth/login |
게시용 키 | 로그인 (?mode=cookie 지원) |
POST |
/auth/token/refresh |
게시용 키 | 토큰 갱신 (refresh 토큰 회전) |
POST |
/auth/logout |
회원 토큰 | 로그아웃 (refresh 토큰 폐기) |
POST |
/auth/password/reset-request |
게시용 키 | 비밀번호 재설정 메일 발송 |
POST |
/auth/password/reset |
게시용 키 | 새 비밀번호 설정, 기존 세션 전부 폐기 |
GET |
/me |
회원 토큰 | 내 정보 조회 |
PATCH |
/me |
회원 토큰 | 프로필·비밀번호 수정 |
DELETE |
/me |
회원 토큰 | 탈퇴 (즉시 삭제, 90일 재가입 제한) |
GET |
/me/consents |
회원 토큰 | 동의 이력 조회 |
PUT |
/me/consents |
회원 토큰 | 동의·철회 기록 추가 |
GET /auth/oauth/{provider}는 소셜 로그인용으로 예약된 경로이며 현재는 501을 반환합니다.
회원 목록 조회, 역할 변경, 정지, 강제 탈퇴, 회원 직접 추가는 API로 제공하지 않습니다. 대시보드의 회원 메뉴에서 관리합니다.
회원 객체
{
"id": "0b6f2c1e-7c3a-4d0e-9a51-2f6f5e1c9b10",
"email": "user@example.com",
"role": "member",
"status": "active",
"emailVerified": true,
"profile": { "name": "홍길동" },
"createdAt": "2026-11-12T03:00:00.000Z",
"lastLoginAt": "2026-11-12T03:05:00.000Z"
}
| 필드 | 설명 |
|---|---|
role |
역할 이름. 기본값 member. 테이블 권한 규칙 role:<이름>에 쓰입니다 |
status |
pending(인증 대기) / active(활성) / suspended(정지) |
profile |
서비스가 정한 자유 형식 객체 (8KB 이내) |
가입과 이메일 인증
POST /auth/signup
{
"email": "user@example.com",
"password": "at-least-8-chars",
"profile": { "name": "홍길동" },
"consents": [
{ "type": "terms", "version": "2026-11", "agreed": true },
{ "type": "privacy", "version": "2026-11", "agreed": true },
{ "type": "marketing", "version": "2026-11", "agreed": false }
]
}
| 필드 | 필수 | 설명 |
|---|---|---|
email |
O | 앞뒤 공백을 지우고 소문자로 바꿔 저장합니다 |
password |
O | 8~128자 |
profile |
자유 형식 객체 | |
consents |
동의 항목. type은 terms, privacy, marketing |
201과 함께 { "member": { … "status": "pending" } }을 반환하고 인증 메일을 보냅니다.
탈퇴한 지 90일이 지나지 않은 이메일은 다시 가입할 수 없으며 409 AUTH_EMAIL_WITHDRAWN이 반환됩니다. 이 기간에는 이메일의 암호화된 값만 보관되고 이후 자동 삭제됩니다.
오류: 400 AUTH_INVALID_REQUEST, 402 AUTH_SIGNUP_PAUSED, 403 AUTH_NOT_ENABLED, 409 AUTH_EMAIL_EXISTS, 409 AUTH_EMAIL_WITHDRAWN, 429 AUTH_RATE_LIMITED
POST /auth/email/verify
메일 링크가 리다이렉트 URL에 붙여 준 token을 보냅니다.
{ "token": "…" }
200과 함께 { "member": { … "status": "active" } }을 반환합니다. 이 시점에 가입 1건의 크레딧이 차감됩니다. 같은 토큰으로 다시 호출해도 성공하며 추가로 차감되지 않습니다.
오류: 401 AUTH_TOKEN_INVALID, 401 AUTH_TOKEN_EXPIRED (링크는 24시간 유효)
POST /auth/email/resend
{ "email": "user@example.com" }
{ "success": true }를 반환합니다. 인증 대기 중인 회원이 아니어도 응답은 같습니다. 같은 이메일에는 1분에 한 번, 하루 5번까지만 보내며 초과하면 429 AUTH_RATE_LIMITED입니다.
로그인과 토큰
POST /auth/login
{ "email": "user@example.com", "password": "at-least-8-chars" }
{
"accessToken": "eyJhbGciOiJFZERTQSIs…",
"refreshToken": "q1W8…",
"expiresIn": 900,
"member": { "id": "…", "email": "user@example.com", "role": "member", "status": "active" }
}
accessToken은 JWT이며expiresIn초 뒤 만료됩니다(기본 15분).- 쿠키 모드(
?mode=cookie또는 "쿠키만" 모드)에서는 토큰을 본문에 넣지 않고httpOnly쿠키로 내려보내며, 본문은{ "expiresIn", "member", "csrfToken" }입니다. 쿠키 모드에서는remember: false로 세션 쿠키를 요청할 수 있습니다.
오류: 401 AUTH_INVALID_CREDENTIALS(이메일·비밀번호 중 어느 쪽이 틀렸는지 구분하지 않음), 403 AUTH_EMAIL_NOT_VERIFIED, 403 AUTH_MEMBER_SUSPENDED, 429 AUTH_RATE_LIMITED
POST /auth/token/refresh
{ "refreshToken": "q1W8…" }
로그인과 같은 형태의 응답을 반환합니다. refresh 토큰은 1회용이라 응답의 새 refreshToken을 저장해야 합니다. 이미 사용한 토큰을 다시 보내면 401 AUTH_TOKEN_INVALID가 반환되고 그 로그인의 세션이 모두 폐기됩니다. 쿠키 모드에서는 빈 본문({})으로 호출합니다.
오류: 401 AUTH_TOKEN_INVALID, 401 AUTH_TOKEN_EXPIRED, 403 AUTH_MEMBER_SUSPENDED
POST /auth/logout
{ "refreshToken": "q1W8…" }
해당 refresh 토큰의 로그인을 끊습니다. { "all": true }를 보내거나 토큰을 생략하면 그 회원의 모든 세션을 끊습니다.
비밀번호 재설정
POST /auth/password/reset-request
{ "email": "user@example.com" }
항상 { "success": true }를 반환합니다. 가입된 이메일인지 알려 주지 않습니다.
POST /auth/password/reset
{ "token": "…", "password": "new-password" }
재설정 링크의 토큰(30분 유효, 1회용)으로 새 비밀번호를 설정합니다. 성공하면 그 회원의 기존 세션이 모두 폐기됩니다.
오류: 401 AUTH_TOKEN_INVALID, 401 AUTH_TOKEN_EXPIRED
내 정보
GET /me
{ "member": { … } }을 반환합니다.
PATCH /me
{
"profile": { "name": "홍길동", "phone": "010-0000-0000" },
"currentPassword": "old-password",
"newPassword": "new-password"
}
profile만, 또는 비밀번호만 보낼 수 있습니다. 비밀번호를 바꾸려면 currentPassword가 필요하며, 바꾸면 모든 세션이 로그아웃됩니다.
DELETE /me
회원 탈퇴입니다. 회원 정보는 즉시 삭제되고 { "success": true }를 반환합니다.
탈퇴한 이메일은 90일 동안 같은 Project에 다시 가입할 수 없습니다. 이 기간에는 이메일의 암호화된 값만 보관되고 이후 자동 삭제됩니다.
GET /me/consents, PUT /me/consents
{ "consents": [{ "type": "marketing", "version": "2026-11", "agreed": false }] }
PUT은 동의 또는 철회를 이력에 추가합니다. 이전 기록은 덮어쓰지 않습니다. 두 엔드포인트 모두 최신순 이력을 반환합니다.
{
"consents": [
{ "type": "marketing", "version": "2026-11", "agreed": false, "agreedAt": "2026-11-12T04:00:00.000Z" },
{ "type": "terms", "version": "2026-11", "agreed": true, "agreedAt": "2026-11-12T03:00:00.000Z" }
]
}
테이블 권한 규칙과 콘텐츠 API
Table에 권한 규칙을 정하면, 게시용 키 요청에 회원 토큰을 함께 보내 콘텐츠 API를 호출할 수 있습니다.
curl -X POST https://api.onttle.com/v1/{projectId}/tables/posts \
-H "X-Onttle-Key: $ONTTLE_PUBLISHABLE_KEY" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "title": "첫 글", "is_publish": true }'
| 규칙 | 회원 토큰 없음 | 권한 없는 회원 |
|---|---|---|
public |
허용 | 허용 |
member |
401 |
— |
owner |
401 |
403 AUTH_FORBIDDEN (목록은 본인 것만 반환) |
role:<이름> |
401 |
403 AUTH_FORBIDDEN |
none |
403 |
403 |
회원 파일 업로드
Project의 파일 업로드 권한이 "로그인한 회원" 또는 "특정 역할"이면 회원 토큰으로 파일을 올릴 수 있습니다. 기본값은 시크릿 키 전용입니다.
curl -X POST https://api.onttle.com/v1/{projectId}/files \
-H "X-Onttle-Key: $ONTTLE_PUBLISHABLE_KEY" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F "file=@./photo.jpg"
응답은 시크릿 키로 업로드할 때와 같은 파일 객체입니다. 반환된 id를 FILE 컬럼 값으로 씁니다.
| 상황 | 응답 |
|---|---|
| 권한이 "비밀 키 전용" | 403 |
| 회원 토큰 없음 | 401 AUTH_TOKEN_INVALID |
| 역할이 맞지 않음 | 403 AUTH_FORBIDDEN |
| 파일이 회원 업로드 최대 크기를 넘음 | 400 AUTH_INVALID_REQUEST |
| 10분에 30회 초과 | 429 AUTH_RATE_LIMITED |
회원 업로드에서는 is_ocr, is_generate가 무시되며, 올린 파일은 그 회원이 탈퇴하면 삭제됩니다.
에러 코드
회원 API의 오류 응답은 다음 형태입니다.
{ "code": "AUTH_INVALID_CREDENTIALS", "message": "The e-mail or password is incorrect." }
| 코드 | HTTP | 상황 |
|---|---|---|
AUTH_INVALID_REQUEST |
400 | 요청 본문이 올바르지 않음 (message에 필드가 표시됨) |
AUTH_INVALID_CREDENTIALS |
401 | 이메일·비밀번호 불일치 (어느 쪽인지 구분하지 않음) |
AUTH_TOKEN_EXPIRED |
401 | 토큰 만료 |
AUTH_TOKEN_INVALID |
401 | 토큰 누락·위조·재사용 |
AUTH_SIGNUP_PAUSED |
402 | 크레딧 소진 또는 월 가입 상한 도달 |
AUTH_EMAIL_NOT_VERIFIED |
403 | 이메일 인증 전 로그인 |
AUTH_MEMBER_SUSPENDED |
403 | 정지된 회원 |
AUTH_FORBIDDEN |
403 | 권한 규칙 위반, CSRF 검사 실패, 허용되지 않은 키 |
AUTH_NOT_ENABLED |
403 | Project에서 회원 기능이 꺼져 있음 |
AUTH_EMAIL_EXISTS |
409 | 이미 가입된 이메일 |
AUTH_EMAIL_WITHDRAWN |
409 | 탈퇴 후 90일 이내 재가입 |
AUTH_RATE_LIMITED |
429 | 요청 횟수 초과 |
AUTH_PROVIDER_NOT_SUPPORTED |
501 | 소셜 로그인 미지원 |
AUTH_TOKEN_EXPIRED를 받으면 /auth/token/refresh로 토큰을 갱신한 뒤 요청을 다시 보냅니다. 갱신도 실패하면 다시 로그인해야 합니다.
다음 단계
- 회원 (가입·로그인) — 회원 기능 설정, 권한 규칙, 쿠키 모드를 확인합니다.
- OpenAPI 명세 — 회원 기능을 켠 Project의 명세에는 회원 엔드포인트와 권한 규칙이 포함됩니다.
- 인증 — API Key 발급과 키 유형을 확인합니다.