핵심 기능

회원 (가입·로그인)

내 서비스의 최종 사용자가 이메일로 가입·로그인하게 하는 회원 기능을 켜고, 테이블 권한 규칙과 쿠키 모드를 설정하는 방법을 설명합니다.

회원 기능을 켜면 Onttle Project로 만든 서비스에 이메일 가입·로그인을 붙일 수 있습니다. 가입, 이메일 인증, 로그인, 토큰 갱신, 비밀번호 재설정, 탈퇴까지 Onttle API가 처리하므로 인증 서버를 따로 만들 필요가 없습니다.

여기서 회원은 내 서비스의 최종 사용자입니다. Onttle 대시보드를 함께 쓰는 Workspace·Project 멤버와는 다릅니다.

항목 내용
로그인 방식 이메일 + 비밀번호 (소셜 로그인은 이후 버전에서 제공)
설정 권한 인증 설정·권한 규칙: Project 소유자(OWNER) 또는 관리자(ADMIN)
관리 권한 회원 조회·정지·강제 탈퇴: Project 편집자(EDITOR) 이상. 회원 직접 추가: 소유자·관리자
과금 이메일 인증을 완료한 가입 1건마다 크레딧 차감. 그 밖의 동작은 무료
격리 회원은 Project 단위로 분리됩니다. 같은 이메일도 Project마다 별도 회원입니다

회원 기능 켜기

  1. Project 좌측 메뉴에서 회원을 엽니다.
  2. 인증 설정 탭에서 회원 기능 켜기를 켭니다.
  3. 처음 켤 때 개인정보 처리 위탁 안내를 확인하고 동의합니다. 회원 기능을 켜면 Onttle이 귀사의 개인정보 처리 수탁자가 되므로, 귀사 개인정보 처리방침에 위탁·국외 이전 내용을 반영해야 합니다.
  4. 아래 항목을 입력하고 저장합니다.
설정 설명
허용 Origin 내 서비스의 주소(https://www.example.com). 한 줄에 하나, 와일드카드는 쓸 수 없습니다
이메일 인증 리다이렉트 URL 가입 인증 메일의 버튼이 연결되는 주소. 허용 Origin 안에 있어야 하며 뒤에 ?token=…이 붙습니다
비밀번호 재설정 리다이렉트 URL 비밀번호 재설정 메일의 버튼이 연결되는 주소. 같은 규칙입니다
발송자 이름 (선택) 인증·재설정 메일의 보내는 사람 이름. 비워 두면 Project 이름을 씁니다 (최대 40자)
Reply-To (선택) 회원이 인증 메일에 답장할 때 받을 주소
access 토큰 만료 5~60분 (기본 15분)
refresh 토큰 만료 1~365일 (기본 30일)
월 가입 상한 (선택) 한 달에 인증을 마칠 수 있는 가입 건수. 도달하면 신규 가입만 중단됩니다
회원 역할 회원에게 줄 수 있는 역할 목록. 기본값은 member 하나이며, 아래 "회원 역할" 참고
파일 업로드 권한 공개 키로 파일을 올릴 수 있는 회원: 비밀 키 전용(기본) / 로그인한 회원 / 특정 역할. 아래 "회원 파일 업로드" 참고
토큰 모드 Bearer만(기본) / Bearer + 쿠키 / 쿠키만. 아래 "쿠키 모드" 참고

설정 변경은 Audit 로그에 기록됩니다.


가입부터 로그인까지

회원 API는 게시용 키(pk-proj_…)를 X-Onttle-Key 헤더로 보내 브라우저나 앱에서 직접 호출합니다. 전체 엔드포인트와 요청·응답은 회원 API에서 확인할 수 있습니다.

1. POST /auth/signup         가입 요청 → 회원은 "인증 대기", 인증 메일 발송
2. (회원) 메일의 버튼 클릭    → 리다이렉트 URL?token=… 로 이동
3. POST /auth/email/verify   토큰 확인 → 회원 "활성", 이때 크레딧 차감
4. POST /auth/login          accessToken + refreshToken 발급
5. GET  /me                  Authorization: Bearer <accessToken>
6. POST /auth/token/refresh  access 토큰이 만료되면 새 토큰 발급
const API = `https://api.onttle.com/v1/${projectId}`
const headers = {
  'X-Onttle-Key': process.env.NEXT_PUBLIC_ONTTLE_PUBLISHABLE_KEY!,
  'Content-Type': 'application/json',
}

// 가입
await fetch(`${API}/auth/signup`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    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 },
    ],
  }),
})

// 리다이렉트 URL 페이지에서: 메일 링크의 token으로 인증 완료
await fetch(`${API}/auth/email/verify`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ token: new URLSearchParams(location.search).get('token') }),
})

// 로그인
const session = await fetch(`${API}/auth/login`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ email: 'user@example.com', password: 'at-least-8-chars' }),
}).then((res) => res.json())

// 로그인한 회원으로 호출
const me = await fetch(`${API}/me`, {
  headers: { ...headers, Authorization: `Bearer ${session.accessToken}` },
}).then((res) => res.json())

알아 둘 동작

  • 인증 메일: Onttle이 발송하며, 보내는 사람 이름은 인증 설정의 발송자 이름(비워 두면 Project 이름)입니다. 발송자 이름에는 줄바꿈·꺾쇠·따옴표 같은 문자와, 고객센터·은행명·대형 플랫폼 이름처럼 사칭으로 보일 수 있는 단어를 쓸 수 없습니다. 커스텀 테마에 로고가 있으면 메일 상단에 표시됩니다. 인증 링크는 24시간, 비밀번호 재설정 링크는 30분 동안 유효하고 한 번만 쓸 수 있습니다.
  • 재발송 제한: 같은 이메일에는 1분에 한 번, 하루 5번까지만 메일을 보냅니다.
  • refresh 토큰은 1회용입니다. 갱신할 때마다 새 토큰이 발급되고 이전 토큰은 폐기됩니다. 이미 쓴 토큰이 다시 오면 탈취로 보고 그 로그인의 세션을 모두 끊습니다. 받은 새 토큰을 반드시 저장해 다음 갱신에 쓰세요.
  • 비밀번호를 바꾸거나 재설정하면 그 회원의 모든 세션이 로그아웃됩니다.
  • 로그인 오류와 비밀번호 재설정 요청은 가입 여부를 알려 주지 않습니다. 이메일이 틀려도 비밀번호가 틀려도 같은 오류가 돌아옵니다.
  • 프로필: profile에는 이름·전화번호처럼 서비스가 정한 값을 자유롭게 저장할 수 있습니다(8KB 이내).

탈퇴와 90일 재가입 제한

회원이 탈퇴(DELETE /me)하거나 관리자가 강제 탈퇴시키면 회원 정보는 즉시 삭제됩니다.

탈퇴한 회원의 이메일은 암호화된 형태로 90일간 보관 후 자동 삭제됩니다. 이 기간에는 같은 이메일로 다시 가입할 수 없습니다.

  • 보관되는 것은 이메일 원문이 아니라 되돌릴 수 없는 값(HMAC)뿐입니다.
  • 90일 안에 같은 이메일로 가입하면 409 AUTH_EMAIL_WITHDRAWN이 돌아옵니다. 가입 화면에 이 안내를 넣어 두세요.
  • 제한은 Project 단위입니다.
  • 관리자는 회원 → 회원 관리 → 재가입 차단 해제에서 특정 이메일의 제한을 풀 수 있습니다.
  • 탈퇴한 회원이 만든 콘텐츠는 삭제되지 않고 작성자 정보만 비워집니다.
  • 탈퇴한 회원이 올린 파일은 함께 삭제됩니다.

테이블 권한 규칙

회원 기능을 쓰면 Table마다 누가 어떤 작업을 할 수 있는지 정할 수 있습니다. Table을 만들거나 수정하는 화면(테이블 폼)에서 API 엔드포인트 스위치 아래에 있는 권한 규칙에서 읽기·생성·수정·삭제별로 하나씩 고르고 저장합니다. API 엔드포인트 명세 화면의 "회원 접근" 안내에 있는 권한 규칙 설정을 눌러도 같은 테이블 폼이 열립니다. Project 소유자(OWNER)와 관리자(ADMIN)가 바꿀 수 있습니다.

규칙 의미 허용되지 않을 때
공개 게시용 키만 있으면 허용 —
로그인한 회원 로그인한 회원이면 허용 401
작성자 본인 그 콘텐츠를 만든 회원만 허용 403 AUTH_FORBIDDEN
특정 역할 해당 역할(role:admin 등)의 회원만 허용 403 AUTH_FORBIDDEN
비밀 키 전용 게시용 키로는 호출할 수 없음 403
  • 기본값은 기존 동작과 같습니다. 읽기는 공개, 생성·수정·삭제는 비밀 키 전용입니다. 규칙을 바꾸지 않은 Table은 아무것도 달라지지 않습니다.
  • 시크릿 키(sk-proj_…) 요청은 규칙과 관계없이 항상 허용됩니다.
  • 작성자는 서버가 정합니다. "로그인한 회원" 이상의 규칙으로 콘텐츠를 생성하면 그 회원이 작성자가 됩니다. 요청 본문으로 작성자를 바꿀 수 없습니다. 시크릿 키로 생성할 때만 owner_member_id로 작성자를 지정할 수 있습니다.
  • "작성자 본인" 규칙의 목록 조회는 오류 대신 본인이 만든 콘텐츠만 돌려주며, pagination.total도 본인 콘텐츠 기준입니다.
  • 회원이 만든 콘텐츠도 is_publish: true로 저장해야 읽기 API에 나옵니다.
  • "특정 역할"에서 고를 수 있는 역할은 인증 설정의 회원 역할 목록입니다. 회원의 역할은 회원 → 회원 관리에서 바꿉니다.

예: 게시판 Table을 "읽기 = 공개, 생성 = 로그인한 회원, 수정·삭제 = 작성자 본인"으로 두면, 누구나 글을 읽고 회원만 글을 쓰며 자기 글만 고치거나 지울 수 있습니다.

// 로그인한 회원으로 글 작성 (규칙: 생성 = 로그인한 회원)
await fetch(`${API}/tables/posts`, {
  method: 'POST',
  headers: { ...headers, Authorization: `Bearer ${session.accessToken}` },
  body: JSON.stringify({ title: '첫 글', body: '…', is_publish: true }),
})

회원 역할

역할은 Project마다 미리 정해 두는 이름 목록입니다. 회원 → 인증 설정 → 회원 역할에서 Project 소유자(OWNER)와 관리자(ADMIN)가 추가하고 삭제합니다.

  • 기본값은 member 하나입니다. member는 지울 수 없고, 가입한 회원은 모두 member로 시작합니다.
  • 역할 이름은 영문 소문자로 시작하고 영문 소문자·숫자·_·-만 쓸 수 있습니다(예: seller, vip). 최대 20개.
  • 회원 역할 변경, 테이블 권한 규칙의 "특정 역할", 파일 업로드 권한의 "특정 역할"은 모두 이 목록에서 고릅니다. 목록에 없는 역할은 쓸 수 없습니다.

역할을 삭제하면

  • 그 역할을 가진 회원은 자동으로 member가 됩니다. 탈퇴되거나 정지되지 않습니다.
  • 그 역할을 쓰던 테이블 권한 규칙과 파일 업로드 권한은 "비밀 키 전용"으로 바뀝니다.
  • 삭제를 누르면 영향받는 회원 수와 규칙 수를 보여 주는 확인 창이 뜨고, 인증 설정을 저장할 때 적용됩니다. 저장한 뒤에는 되돌릴 수 없으며, 같은 이름의 역할을 다시 만들어도 회원과 규칙은 복구되지 않습니다.

회원 파일 업로드

파일 업로드 API(POST /files)는 기본적으로 시크릿 키 전용입니다. 인증 설정의 파일 업로드 권한을 바꾸면 로그인한 회원이 게시용 키로 직접 파일을 올릴 수 있습니다. 프로필 사진이나 게시글 첨부 파일에 사용합니다.

권한 의미
비밀 키 전용 게시용 키로는 업로드할 수 없습니다 (기본값)
로그인한 회원 로그인한 회원이면 업로드할 수 있습니다
특정 역할 해당 역할(role:seller 등)의 회원만 업로드합니다
const form = new FormData()
form.append('file', file)

const uploaded = await fetch(`${API}/files`, {
  method: 'POST',
  headers: {
    'X-Onttle-Key': process.env.NEXT_PUBLIC_ONTTLE_PUBLISHABLE_KEY!,
    Authorization: `Bearer ${session.accessToken}`,
  },
  body: form,
}).then((res) => res.json())

// 받은 파일 id를 FILE 컬럼 값으로 사용합니다
await fetch(`${API}/tables/posts`, {
  method: 'POST',
  headers: { ...headers, Authorization: `Bearer ${session.accessToken}` },
  body: JSON.stringify({ title: '사진 올립니다', image: uploaded.id, is_publish: true }),
})
  • 크기 제한: 회원이 올리는 파일 하나의 최대 크기를 정합니다(기본 10MB, 최대 500MB). 요금제의 파일 크기 한도와 저장 용량 한도도 그대로 적용됩니다.
  • 로그인하지 않은 업로드는 허용하지 않습니다. 업로드는 저장 용량과 크레딧을 쓰기 때문입니다.
  • 회원 업로드에서는 OCR과 AI 키워드 생성 옵션(is_ocr, is_generate)이 무시됩니다.
  • 한 회원이 짧은 시간에 올릴 수 있는 횟수에 제한이 있습니다(10분에 30회). 초과하면 429 AUTH_RATE_LIMITED입니다.
  • 회원이 올린 파일은 그 회원이 탈퇴하면 함께 삭제됩니다.
  • 업로드는 기존 파일 업로드 지표대로 과금됩니다.
  • 시크릿 키 업로드는 설정과 관계없이 지금까지와 똑같이 동작합니다.

쿠키 모드

기본값인 Bearer 모드에서는 토큰이 응답 본문으로 오고, 앱이 직접 보관합니다. 쿠키 모드에서는 토큰을 응답 본문 대신 httpOnly 쿠키로 내려보내 JavaScript가 토큰에 접근할 수 없게 합니다.

쿠키 모드는 커스텀 도메인이 연결된 Workspace에서만 쓸 수 있습니다. 쿠키가 내 서비스와 같은 사이트의 것이어야 브라우저가 차단하지 않기 때문입니다.

설정 설명
토큰 모드 Bearer + 쿠키: ?mode=cookie로 로그인할 때만 쿠키 사용. 쿠키만: Bearer 토큰을 받지 않음(모바일 앱 불가)
쿠키 도메인 연결이 완료된 커스텀 도메인 중에서 선택 (예: cms.onttle.com). 직접 입력할 수 없습니다
SameSite Lax(기본) / Strict / None. None은 서드파티 쿠키를 차단하는 브라우저에서 동작하지 않습니다

쿠키 모드에서는 API를 api.onttle.com이 아니라 쿠키 도메인으로 호출합니다.

const API = `https://cms.onttle.com/v1/${projectId}` // 쿠키 도메인

// 로그인: 토큰은 쿠키로 오고, 본문에는 csrfToken이 옵니다
const { csrfToken } = await fetch(`${API}/auth/login?mode=cookie`, {
  method: 'POST',
  credentials: 'include',
  headers,
  body: JSON.stringify({ email, password, remember: true }),
}).then((res) => res.json())

// 쓰기 요청: csrfToken을 헤더로 함께 보냅니다
await fetch(`${API}/me`, {
  method: 'PATCH',
  credentials: 'include',
  headers: { ...headers, 'X-CSRF-Token': csrfToken },
  body: JSON.stringify({ profile: { name: '홍길동' } }),
})
  • CSRF 보호는 항상 켜져 있습니다. 쿠키로 인증한 쓰기 요청(POST, PUT, PATCH, DELETE)은 허용 Origin에서 보내야 하고 X-CSRF-Token 헤더가 필요합니다. 조회(GET)에는 필요 없습니다.
  • 페이지를 새로 열면 POST /auth/token/refresh를 빈 본문으로 호출해 새 csrfToken을 받습니다.
  • 허용 Origin 중 하나 이상이 쿠키 도메인과 같은 사이트(예: www.onttle.com과 cms.onttle.com)여야 저장됩니다.
  • remember: false로 로그인하면 브라우저를 닫을 때 로그아웃되는 세션 쿠키가 발급됩니다.
  • 토큰 모드를 바꾸면 회원이 로그아웃될 수 있습니다. "쿠키만"으로 바꾸거나 쿠키 모드를 끄거나 쿠키 도메인을 바꾸면 모든 회원 세션이 끊깁니다. 저장 전에 현재 로그인 중인 회원 수가 표시됩니다.
  • 로컬 개발 환경(localhost)은 쿠키 도메인과 같은 사이트가 아니므로 Bearer 모드로 개발하세요.

Next.js처럼 서버가 있는 프레임워크라면, 쿠키 모드 없이 서버가 토큰을 받아 자기 도메인의 쿠키로 저장하는 방식(BFF)도 쓸 수 있습니다. 이 경우 Bearer 모드 그대로 서버에서 Onttle API를 호출합니다.


회원 관리

회원 → 회원 관리에서 가입한 회원을 확인하고 관리합니다.

작업 설명
회원 추가 소유자·관리자가 이메일과 비밀번호로 회원을 바로 등록합니다. 아래 "회원 직접 추가" 참고
검색 이메일 전체를 입력해 검색합니다. 이메일은 암호화해 저장하므로 일부만으로는 찾을 수 없습니다
역할 변경 권한 규칙의 "특정 역할"에 쓰이는 역할 이름을 바꿉니다
정지 / 정지 해제 정지하면 모든 기기에서 즉시 로그아웃되고 로그인할 수 없습니다
강제 탈퇴 회원 정보를 즉시 삭제합니다. 90일 재가입 제한이 똑같이 적용됩니다
재가입 차단 해제 탈퇴한 이메일의 90일 제한을 풉니다

회원 관리는 대시보드에서 합니다. REST API에는 회원 목록이나 역할 변경을 위한 엔드포인트가 없습니다. MCP 서버를 계정 로그인으로 연결하면 AI 클라이언트에서 회원 목록 조회, 역할 변경, 정지·해제, 회원 직접 추가를 할 수 있습니다. 강제 탈퇴는 대시보드에서만 할 수 있습니다.

회원 직접 추가

Project 소유자(OWNER)와 관리자(ADMIN)는 회원 추가 버튼으로 회원을 바로 등록할 수 있습니다. 이메일, 비밀번호, 역할을 입력합니다.

  • 직접 추가한 회원에게는 인증 메일이 발송되지 않고, 이메일이 인증된 것으로 처리됩니다. 등록 전에 "이 이메일을 인증된 것으로 처리합니다" 스위치를 켜서 한 번 더 확인해야 합니다. 주소가 정확한지 확인한 뒤 켜세요.
  • 등록 즉시 활성 상태가 되어 바로 로그인할 수 있습니다. 비밀번호는 회원에게 따로 전달하고, 회원은 로그인 후 바꿀 수 있습니다.
  • 가입 1건으로 집계되어 크레딧이 차감되며, 월 가입 상한과 90일 재가입 제한도 똑같이 적용됩니다.
  • 누가 언제 추가했는지 Audit 로그에 기록됩니다.

과금

동작 크레딧
회원 가입 (이메일 인증 완료 시) 가입 1건마다 차감
대시보드에서 회원 직접 추가 추가 1건마다 차감
로그인, 토큰 갱신, 로그아웃, 실패한 로그인 없음
인증·재설정 메일 발송 없음
탈퇴 없음
  • 인증을 마치지 않은 가입은 차감되지 않습니다. 같은 인증 링크를 여러 번 눌러도 한 번만 차감됩니다.
  • 크레딧이 부족하거나 월 가입 상한에 도달하면 신규 가입만 402 AUTH_SIGNUP_PAUSED로 중단됩니다. 기존 회원의 로그인·갱신·탈퇴는 계속 동작합니다.
  • 회원 토큰으로 호출한 콘텐츠 API는 기존 API 호출 지표대로 집계됩니다.
  • 가입 건수는 사용량 화면의 "회원 가입" 항목에서 확인합니다.

보안

  • 비밀번호는 argon2id로 해시해 저장합니다. 최소 8자입니다.
  • 이메일은 암호화해 저장하고, 조회에는 Project별 키로 만든 해시를 씁니다.
  • refresh 토큰과 메일 링크 토큰은 원문을 저장하지 않습니다.
  • 가입·로그인·메일 발송에는 IP와 이메일 기준 요청 제한이 걸려 있습니다. 초과하면 429 AUTH_RATE_LIMITED가 돌아옵니다.

다음 단계

  • 회원 API — 엔드포인트별 요청·응답과 에러 코드를 확인합니다.
  • 인증 — X-Onttle-Key 헤더와 키 유형을 확인합니다.
  • 커스텀 도메인 — 쿠키 모드에 필요한 도메인을 연결합니다.