API 레퍼런스

API 레퍼런스

Authon 인증 서비스에 대한 완전한 REST API 문서. 모든 요청에는 x-api-key 헤더의 API 키 또는 Bearer 토큰이 포함되어야 합니다. Authorization.

기본 URL

text
https://api.authon.dev

인증

Authon은 요청이 브라우저에서 오는지 서버에서 오는지에 따라 두 가지 유형의 API 키를 사용합니다. x-api-key 헤더나 Bearer 토큰으로 키를 전달하세요.

키 유형접두사사용
공개 키pk_live_ / pk_test_브라우저 / 클라이언트 SDK. 노출해도 안전.
비밀 키sk_live_ / sk_test_서버 전용. 전체 관리자 접근. 절대 노출 금지.
BearereyJhbGci...로그인 시 받는 사용자 액세스 토큰. 15분 TTL.
bash
# Publishable key — client-side requests
curl https://api.authon.dev/v1/auth/providers \
  -H "x-api-key: pk_live_your_publishable_key"

# Secret key — server-side admin requests
curl https://api.authon.dev/v1/auth/token/verify \
  -H "x-api-key: sk_live_your_secret_key" \
  -H "Authorization: Bearer eyJhbGci..."

# Bearer access token — user requests
curl https://api.authon.dev/v1/auth/me \
  -H "Authorization: Bearer eyJhbGci..."

인증 엔드포인트

POST/v1/auth/signup

회원가입

이메일과 비밀번호로 새 사용자를 등록합니다. 성공 시 토큰을 반환합니다.

Auth:x-api-key: pk_live_...
요청 본문
json
{
  "email": "user@example.com",
  "password": "securepassword",
  "displayName": "Jane Doe"          // optional
}
응답
json
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_8f4a2b1c...",
  "expiresIn": 900,
  "user": {
    "id": "usr_abc123",
    "projectId": "proj_xyz",
    "email": "user@example.com",
    "displayName": "Jane Doe",
    "avatarUrl": null,
    "emailVerified": false,
    "isBanned": false,
    "publicMetadata": null,
    "signInCount": 0,
    "createdAt": "2026-01-15T10:30:00.000Z",
    "updatedAt": "2026-01-15T10:30:00.000Z"
  }
}
POST/v1/auth/signin

로그인

이메일과 비밀번호로 기존 사용자를 인증합니다.

Auth:x-api-key: pk_live_...
요청 본문
json
{
  "email": "user@example.com",
  "password": "securepassword"
}
응답
json
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt_8f4a2b1c...",
  "expiresIn": 900,
  "user": { ... }
}
POST/v1/auth/signout

로그아웃

현재 세션을 취소하고 리프레시 토큰을 무효화합니다. Bearer 액세스 토큰이 필요합니다.

Auth:Authorization: Bearer <access_token>
응답
json
{
  "success": true
}
POST/v1/auth/token/refresh

토큰 갱신

리프레시 토큰을 새 액세스 토큰으로 교환합니다. 액세스 토큰은 15분 후 만료됩니다.

Auth:x-api-key: pk_live_...
요청 본문
json
{
  "refreshToken": "rt_8f4a2b1c..."
}
응답
json
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 900
}
GET/v1/auth/token/verify

토큰 검증

액세스 토큰을 검증하고 연관된 사용자를 반환합니다. 서버 SDK가 수신 요청을 인증하는 데 사용합니다.

Auth:x-api-key: sk_live_...
응답
json
{
  "id": "usr_abc123",
  "projectId": "proj_xyz",
  "email": "user@example.com",
  "displayName": "Jane Doe",
  "emailVerified": true,
  "isBanned": false,
  "publicMetadata": { "plan": "pro" },
  "signInCount": 42,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}
GET/v1/auth/me

현재 사용자 조회

현재 인증된 사용자의 프로필을 반환합니다.

Auth:Authorization: Bearer <access_token>
응답
json
{
  "id": "usr_abc123",
  "projectId": "proj_xyz",
  "email": "user@example.com",
  "displayName": "Jane Doe",
  "avatarUrl": "https:0
  6: null,
  7: true,
  8: false,
  9: false,
  10: {},
  11: "2026-01-15T10:30:00.000Z",
  "signInCount": 42,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}
PATCH/v1/auth/me

현재 사용자 업데이트

현재 인증된 사용자의 프로필 필드를 업데이트합니다. 제공된 필드만 업데이트됩니다.

Auth:Authorization: Bearer <access_token>
요청 본문
json
{
  "displayName": "Jane Smith",          // optional
  "avatarUrl": "https://example.com/avatar.png"  // optional
}
응답
json
{
  "id": "usr_abc123",
  "displayName": "Jane Smith",
  "avatarUrl": "https://example.com/avatar.png",
  ...
}

OAuth 엔드포인트

GET/v1/auth/providers

제공자 목록

프로젝트에서 활성화된 OAuth 제공자 목록을 반환합니다.

Auth:x-api-key: pk_live_...
응답
json
{
  "providers": ["google", "github", "kakao"]
}
GET/v1/auth/oauth/:provider/url

OAuth URL 가져오기

주어진 OAuth 제공자의 인증 URL을 생성합니다. 사용자를 리디렉션하거나 팝업을 여는 데 사용하세요.

Auth:x-api-key: pk_live_...
응답
json
{
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=..."
}
POST/v1/auth/oauth/callback

OAuth 콜백

OAuth 인증 코드를 Authon 토큰으로 교환합니다. 팝업 반환 후 SDK가 호출합니다.

Auth:x-api-key: pk_live_...
요청 본문
json
{
  "provider": "google",
  "code": "4/0AX4XfWh...",
  "state": "random_state_string",
  "codeVerifier": "pkce_verifier"   // required if PKCE was used
}
응답
json
{
  "accessToken": "eyJhbGci...",
  "refreshToken": "rt_...",
  "expiresIn": 900,
  "user": { ... }
}

브랜딩

GET/v1/auth/branding

브랜딩 조회

프로젝트의 브랜딩 설정을 반환합니다. JS SDK가 로그인 모달 스타일링에 사용합니다.

Auth:x-api-key: pk_live_...
응답
json
{
  "brandName": "Acme Corp",
  "primaryColorStart": "#7c3aed",
  "primaryColorEnd": "#4f46e5",
  "lightBg": "#ffffff",
  "lightText": "#111827",
  "darkBg": "#0f172a",
  "darkText": "#f1f5f9",
  "borderRadius": 12,
  "showEmailPassword": true,
  "showDivider": true,
  "termsUrl": "https:0
  13: "https://acme.com/privacy",
  "logoDataUrl": "data:image/png;base64,..."
}

오류 코드

모든 오류 응답은 HTTP 상태 코드와 JSON 본문으로 일관된 형식을 따릅니다:

json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or expired access token"
}
상태오류설명
400Bad Request요청 본문이 없거나 형식이 잘못됨
401UnauthorizedAPI 키 / 토큰이 없거나 유효하지 않거나 만료됨
403Forbidden키는 유효하지만 이 작업에 대한 권한이 없음
404Not Found요청한 리소스가 존재하지 않음
409Conflict이미 등록된 이메일
422Unprocessable Entity유효성 검사 실패 — 필드 요구사항을 확인하세요
429Too Many Requests요청 한도 초과 — 지정된 지연 후 재시도하세요
500Internal Server Error예기치 않은 서버 측 오류
Authon — 범용 인증 플랫폼