Skip to main content

인증 API

사용자 인증 및 토큰 관리를 위한 API 레퍼런스입니다.

개요​

Multi-SaaS Kit은 Laravel Sanctum 기반의 토큰 인증을 사용합니다.

항목설명
인증 방식Bearer Token (Sanctum)
토큰 형식{token_id}|{random_string}
헤더Authorization: Bearer \{token\}
만료설정 가능 (기본: 무제한)

엔드포인트​

POST /api/v1/auth/login​

사용자 로그인 및 액세스 토큰 발급

Request​

POST /api/v1/auth/login
Content-Type: application/json
{
  "email": "user@example.com",
  "password": "password123",
  "device_name": "web-browser"
}
파라미터타입필수설명
emailstring✅이메일 주소
passwordstring✅비밀번호
device_namestring✅디바이스 식별자

Response​

성공 (200 OK)

{
  "success": true,
  "data": {
    "token": "1|abc123def456...",
    "token_type": "Bearer",
    "user": {
      "id": 1,
      "name": "홍길동",
      "email": "user@example.com",
      "permission_level": 6,
      "tenant_id": 1
    }
  }
}

실패 (401 Unauthorized)

{
  "success": false,
  "message": "The provided credentials are incorrect.",
  "errors": {
    "email": ["인증 정보가 올바르지 않습니다."]
  }
}

POST /api/v1/auth/logout​

현재 토큰 무효화 (로그아웃)

Request​

POST /api/v1/auth/logout
Authorization: Bearer YOUR_TOKEN

Response​

성공 (200 OK)

{
  "success": true,
  "message": "로그아웃되었습니다."
}

POST /api/v1/auth/logout-all​

모든 디바이스에서 로그아웃 (모든 토큰 무효화)

Request​

POST /api/v1/auth/logout-all
Authorization: Bearer YOUR_TOKEN

Response​

성공 (200 OK)

{
  "success": true,
  "message": "모든 세션에서 로그아웃되었습니다.",
  "data": {
    "revoked_tokens": 3
  }
}

GET /api/v1/auth/me​

현재 인증된 사용자 정보 조회

Request​

GET /api/v1/auth/me
Authorization: Bearer YOUR_TOKEN

Response​

성공 (200 OK)

{
  "success": true,
  "data": {
    "id": 1,
    "name": "홍길동",
    "email": "user@example.com",
    "email_verified_at": "2024-01-01T00:00:00Z",
    "permission_level": 6,
    "permission_level_name": "Member",
    "tenant": {
      "id": 1,
      "name": "Example Tenant",
      "slug": "example"
    },
    "organization": {
      "id": 1,
      "name": "Example Org"
    },
    "workspace": {
      "id": 1,
      "name": "Default Workspace"
    },
    "created_at": "2024-01-01T00:00:00Z"
  }
}

POST /api/v1/auth/refresh​

토큰 갱신 (새 토큰 발급)

참고

Sanctum은 기본적으로 토큰 갱신을 지원하지 않습니다. 이 엔드포인트는 기존 토큰을 폐기하고 새 토큰을 발급합니다.

Request​

POST /api/v1/auth/refresh
Authorization: Bearer YOUR_TOKEN

Response​

성공 (200 OK)

{
  "success": true,
  "data": {
    "token": "2|xyz789abc...",
    "token_type": "Bearer"
  }
}

토큰 관리​

토큰 생성 시 능력(Abilities) 설정​

토큰에 특정 권한만 부여할 수 있습니다.

// 모든 권한
$token = $user->createToken('api-token');

// 읽기 전용
$token = $user->createToken('read-only', ['read']);

// 특정 리소스만
$token = $user->createToken('tenant-manager', ['tenant:read', 'tenant:write']);

토큰 만료 설정​

// config/sanctum.php
'expiration' => 60 * 24, // 24시간 (분 단위)

// 또는 토큰 생성 시 개별 설정
$token = $user->createToken('temp-token');
$token->accessToken->expires_at = now()->addHours(1);
$token->accessToken->save();

오류 코드​

HTTP 코드코드설명
401unauthenticated인증되지 않음 (토큰 없음/만료)
401invalid_credentials잘못된 로그인 정보
403forbidden권한 없음
422validation_error입력값 검증 실패
429too_many_requestsRate Limit 초과

Rate Limiting​

인증 관련 API는 브루트포스 공격 방지를 위해 Rate Limit이 적용됩니다.

엔드포인트제한
/auth/login5회/분 (IP 기준)
/auth/logout60회/분
/auth/me60회/분

Rate Limit 초과 시 응답:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
{
  "success": false,
  "message": "Too many login attempts. Please try again in 60 seconds."
}

사용 예제​

cURL​

# 로그인
curl -X POST https://api.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123","device_name":"curl"}'

# 사용자 정보 조회
curl -X GET https://api.example.com/api/v1/auth/me \
  -H "Authorization: Bearer 1|abc123..."

# 로그아웃
curl -X POST https://api.example.com/api/v1/auth/logout \
  -H "Authorization: Bearer 1|abc123..."

JavaScript (Fetch)​

// 로그인
const loginResponse = await fetch('/api/v1/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'password123',
    device_name: 'web-app',
  }),
});

const { data } = await loginResponse.json();
const token = data.token;

// 인증된 요청
const userResponse = await fetch('/api/v1/auth/me', {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

PHP (Laravel HTTP Client)​

use Illuminate\Support\Facades\Http;

// 로그인
$response = Http::post('https://api.example.com/api/v1/auth/login', [
    'email' => 'user@example.com',
    'password' => 'password123',
    'device_name' => 'laravel-app',
]);

$token = $response->json('data.token');

// 인증된 요청
$user = Http::withToken($token)
    ->get('https://api.example.com/api/v1/auth/me')
    ->json('data');

2FA 인증 (선택)​

Two-Factor Authentication 플러그인이 활성화된 경우:

2FA가 필요한 로그인​

// 로그인 응답
{
  "success": false,
  "requires_2fa": true,
  "message": "2단계 인증이 필요합니다.",
  "data": {
    "two_factor_token": "temp_2fa_abc123..."
  }
}

2FA 코드 제출​

POST /api/v1/auth/two-factor
Content-Type: application/json
{
  "two_factor_token": "temp_2fa_abc123...",
  "code": "123456"
}

관련 문서​