본문으로 건너뛰기
가이드

보호된 API 추가하기

Note의 작업 권한과 레코드 범위를 유지하며 API를 확장합니다.

보호된 API 추가하기

Note 수정 요청을 보호합니다. Resource 만들기로 생성했다면 권한·Policy·Route·Controller가 이미 있습니다. App의 src/Policies/NotePolicy.php를 열면 수정 권한과 레코드 범위를 함께 확인합니다.

코드 예시
PHP
public function update(Actor $user, Note $note): bool
{
    return $this->allowsPermission($user, 'workshop.note.update')
        && $this->matchesAuthorizationContract($note);
}

필요한 import와 private helper는 생성된 파일에 있습니다. src/Http/Controllers/NoteController.php에서는 공개 UUID로 조회 → 저장된 소유자 복원 → update 인가 → 입력 검증 → 저장 순서를 유지합니다. 새 입력 항목은 데이터 모델과 마이그레이션를 따라 연결하세요.

샌드박스의 개발 앱을 준비할 때 리소스·권한 선언은 해당 소스 버전에 묶여 등록됩니다. 권한 항목이 등록되어도 사용자나 역할에 자동 부여되지는 않습니다. Policy의 작업 권한 검사와 레코드 범위 검사를 모두 유지하세요. 새 선언에서 제거한 개발 앱 권한은 샌드박스에서 사용 중지되며 기록은 보존됩니다. 다른 앱의 권한 키나 소유권을 재사용하지 마세요.

보관 상태 준비

생성된 Note에는 status 컬럼이나 enum이 없습니다. 아래 예제는 문자열 draft·archived를 사용합니다. 기존 Note 생성 파일을 바꾸지 말고 그보다 뒤의 새 파일 database/migrations/tenant/2026_10_04_130000_add_status_to_wsp_notes.php를 추가하세요. 다른 접두사로 앱을 만들었다면 실제 테이블명을 사용합니다.

코드 예시
PHP
<?php

declare(strict_types=1);

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('wsp_notes', function (Blueprint $table): void {
            $table->string('status', 16)->default('draft');
        });
    }

    public function down(): void
    {
        Schema::table('wsp_notes', function (Blueprint $table): void {
            $table->dropColumn('status');
        });
    }
};

데이터 모델과 마이그레이션의 순서로 동기화·nexia db migrate·완료 확인을 마친 뒤 개발을 재개합니다. 기존 행도 draft로 초기화되므로 실제 업무 데이터에는 이 기본값이 적절한지 먼저 판단하세요. 상태는 전용 동작만 변경하므로 $fillable에 추가하지 않습니다. 응답의 Note 타입에는 status: 'draft' | 'archived'를 추가합니다.

보관 동작 추가

초안 노트를 보관하고 이미 보관된 노트의 반복 요청에는 409를 반환하는 예제입니다. 아래 코드는 App의 생성된 클래스에 멤버로 추가하고 Route는 기존 보호 그룹 안에 넣습니다. 파일 전체를 교체하지 않습니다.

코드 예시
PHP
// NoteModule::permissionResources(): keep the existing actions and add archive.
return [
    'workshop.note' => ['read', 'create', 'update', 'delete', 'archive'],
];
코드 예시
PHP
// Add to NotePolicy; reuse its existing Actor, Note and authorization helpers.
public function archive(Actor $user, Note $note): bool
{
    return $this->allowsPermission($user, 'workshop.note.archive')
        && $this->matchesAuthorizationContract($note);
}
코드 예시
PHP
// routes/routes.php: inside the existing api/workshop prefix and guarded App group.
Route::post('/notes/{note}/archive', [NoteController::class, 'archive'])
    ->whereUuid('note');
코드 예시
PHP
// NoteController: add the DB import; the other imports already exist.
use Illuminate\Support\Facades\DB;

public function archive(Request $request, string $note): JsonResponse
{
    $record = $this->resolveNote($request, $note, 'workshop.note.archive');

    return DB::transaction(function () use ($request, $record): JsonResponse {
        $locked = Note::query()->whereKey($record->getKey())
            ->lockForUpdate()->firstOrFail();
        $this->authorize('archive', $locked);
        abort_if($locked->status === 'archived', 409);
        $locked->status = 'archived';
        $locked->save();

        return response()->json([
            'note' => $this->serialize(
                $request,
                $locked,
                app(ResourceActionDecisions::class),
            ),
        ]);
    });
}

NoteController::store()와 update()의 검증 배열에 'status' => ['missing']를 추가합니다. 새 노트는 DB 기본값 draft를 사용하고 일반 수정으로 보관 권한을 우회할 수 없게 됩니다. missing은 null이나 빈 값으로 전달한 status도 거부합니다. 다른 필드 규칙은 유지하세요. 각 언어에 permissions.keys.workshop.note.archive.label과 .description을 추가합니다. 영어는 Archive Notes / Allows archiving Notes., 한국어는 노트 보관 / 노트를 보관할 수 있습니다., 중국어는 归档笔记 / 允许归档笔记。입니다.

이 동작은 요청의 상태·소유자를 받지 않습니다. 기존 resolver가 소유 범위를 복원하고 행 잠금이 동시 보관의 중복 성공을 막습니다. 버튼은 App 화면 만들기의 흐름에 인가된 action decision으로 연결합니다. 상태만으로 권한을 추정하지 않습니다.

선언을 바꾼 뒤 nexia check를 실행하고 Sandbox에서 반영된 권한 정의와 리소스 연결을 확인합니다. 플랫폼이 Host 등록과 캐시를 관리합니다. 권한 정의를 추가했다고 사용자에게 그 권한이 자동 배정되지는 않습니다.

목록 범위 보호

단건 Policy만으로 목록은 보호되지 않습니다. 생성 모델은 ResourceAuthorization::scopeVisible()을 사용하고 Legal Entity 목록 Controller는 페이지의 허용 대상을 먼저 해석합니다. 목록·내보내기·일괄 작업에서도 이 조건을 유지하세요. 페이지 처리 전 SQL에서 제한해야 금지된 행과 집계가 새지 않습니다.

생성은 creationAttributes()와 인가된 단일 대상을 사용합니다. 요청의 숫자 소유자 ID를 신뢰하거나 저장된 소유자를 덮어쓰지 않습니다. 일반 목록의 선택기는 useOrganizationListScope와 NxOrganizationTargetSelector로 NxPageFrame.organizationScope에 배치합니다. 테넌트 공통 기준정보에는 선택기가 없습니다.

목록 부가 정보는 페이지 단위로 조회

목록에 표시할 이름·건수·수정 제한 여부는 권한이 적용된 페이지를 기준으로 모아서 조회하세요. 각 행을 직렬화하는 반복문 안에서 SQL이나 호스트 호출을 추가하지 않습니다. 관련 레코드는 eager loading, 건수는 집계, 존재 여부는 EXISTS처럼 필요한 결과에 맞는 조회를 사용합니다. 존재 여부만 확인하려고 과거 내역을 전부 불러오지 마세요. 빈 페이지에는 부가 조회가 필요하지 않습니다. 관련 조회에서도 같은 테넌트와 필요한 권한 범위, 논리 삭제 조건을 유지합니다.

예를 들어 25개 행마다 6개 의존 테이블을 확인하면 최대 150번 조회할 수 있습니다. 현재 페이지의 ID만 대상으로 상관 EXISTS 조회를 한 번 수행해 제한 대상 ID를 얻고, 직렬화에서는 그 결과를 참조할 수 있습니다. 어떤 의존 관계가 수정을 막는지는 앱의 업무 규칙입니다. 수정·삭제 시에는 현재 의존 관계와 권한을 다시 확인하며, 목록에 표시했던 제한 여부를 이후 쓰기의 허가로 사용하지 않습니다.

다른 앱의 참조는 올바른 조회 문맥과 공개 ResourceReferences::resolveMany() 계약을 사용하세요. 다른 앱이나 Core의 테이블을 직접 조인하지 않습니다. 일괄 API라고 내부 조회도 한 번이라는 보장은 없으므로 제공자 측 비용도 확인합니다. 공통 권한·서명·카탈로그 처리의 반복 비용은 개발자 지원에 보고하고, 앱에서 Core의 검사나 캐시를 복제하지 마세요. 측정 기준은 App 테스트하기를 따릅니다.

권한이 적용된 현재 페이지에서 ID를 모으고, 행을 직렬화하기 전에 참조를 조회한 뒤 ID로 결과를 연결합니다. owner_party_public_id가 있는 페이지와 해당 페이지의 조회 문맥 $context를 사용한 예입니다.

코드 예시
PHP
use Nexia\ResourceReference\Contracts\ResourceReferences;

$ids = $page->getCollection()->pluck('owner_party_public_id')
    ->filter()->unique()->values()->all();
$owners = app(ResourceReferences::class)->resolveMany('directory.party', $ids, $context);
// 행 직렬화 시: $owners[$row->owner_party_public_id] ?? null.

빈 페이지에서는 참조를 호출하지 않습니다. SDK가 중복 ID를 제거하고 원격 요청을 최대 100개씩 자동으로 나눕니다. Resource 키나 권한 문맥(사용자·조직·기준 시점·조회 목적)이 다르면 별도 배치로 조회합니다. 없거나 권한이 없는 참조는 결과에서 빠집니다. 빠진 ID를 단건으로 재시도하거나 존재 여부를 노출하지 마세요. 조회 결과는 화면 표시용이며 이후 쓰기의 권한 근거가 아닙니다. 제공 App 내부의 일괄 처리는 선택 계약 ResourceReferenceBatchResolutionContribution이 담당합니다. SDK 통신을 묶는 것만으로 App 내부 SQL N+1까지 없어지지는 않습니다.

HTTP 경계 확인

권한이 있는 노트에 POST /api/workshop/notes/{public_id}/archive를 호출하면 200과 status: "archived"를 받습니다. 같은 요청을 반복하면 409, 일반 생성·수정에 status를 넣어 전환을 우회하면 422여야 합니다.

테넌트에 App이 설치된 fixture로 실제 endpoint를 호출합니다. 허용 사용자, 권한 없는 사용자, 다른 조직, 다른 테넌트를 확인하세요. 범위 밖 레코드는 의도적으로 404가 될 수 있습니다. 생성 Controller가 일부 소유자 해석 실패를 숨기므로 모든 거부를 403으로 단정하지 않습니다.

App 테스트하기에서 선언 검사와 동작 검사를 구분합니다. 메뉴·버튼·응답의 actions는 화면을 위한 정보이며 서버 검사를 대신하지 않습니다.

분리 개발 런타임 요청에서는 Core가 사용자의 기존 AccessGrant를 평가하고 해당 앱의 권한 판단을 요청에 서명하여 전달합니다. 런타임은 기존 SDK PermissionAuthorizer로 그 결과를 제공합니다. 누락·거절된 권한, 다른 앱의 권한, 요청 사용자와 다른 주체는 허용하지 않습니다. 테넌트 범위 판단으로 법인·운영 조직 범위를 허용하지 않으며, 앱 정책의 레코드 소유권 검사는 계속 유지해야 합니다.

워크스페이스 선택은 선택적인 화면 문맥이며 권한 범위가 아닙니다. Core가 사용자의 워크스페이스 접근 여부를 확인한 뒤 식별자를 서명하고, 접근할 수 없는 선택은 비워 둡니다. 분리 요청의 임시 세션에는 검증한 화면 문맥만 담으며 요청 처리 후 지웁니다. Core 세션 쿠키는 앱으로 전달하지 않습니다.

CLI 명령과 옵션은 공개 CLI 문서에서도 확인할 수 있습니다.

저장 결과 복구

개발 앱을 시작할 때 플랫폼이 사용하는 DB 구조를 먼저 준비합니다. 미적용 앱 마이그레이션과 시더는 실행하지 않으므로 앱 소유 변경은 기존 DB 명령으로 적용하세요. 대응하는 Core와 Manager/runtime을 적용하면 롤백된 개발 저장의 DB 오류 종류, SQLSTATE와 제한된 DB 식별자를 확인할 수 있으며 SQL 값은 노출하지 않습니다.

저장 응답이 중단되면 호스트가 원래 요청을 유지하고 영수증을 자동으로 확인합니다. 결과를 처리하는 동안 폼은 대기 상태를 유지합니다. 초기 복구 시간이 지나도 서버가 조건에 맞는 영수증을 다시 확인합니다. 매번 원래 사용자, 실행 환경과 DB 연속성을 검사하며 결과가 불확실한 저장은 자동 재실행하지 않습니다. 원래 저장이 중단됐고 부분적인 Core 저장 없이 차단된 것으로 확인된 경우에만 결정적인 새 요청 ID로 한 번 다시 실행할 수 있습니다.

완료된 영수증은 실제 응답 또는 확정된 거절을 돌려줍니다. 202는 접수이며 커밋을 의미하지 않습니다. Core에 일부 변경이 반영됐거나 권한·DB 연속성이 끊긴 경우 실패로 단정하지 않고 원래 요청 참조를 보존해 플랫폼이 조사해야 합니다. 브라우저 종료나 지속적인 인프라 장애는 화면의 대기를 중단시킬 수 있습니다. Core와 Manager/runtime 업데이트가 함께 필요하며 SDK 업데이트는 필요하지 않습니다. Core 구현.

외부 클라이언트와 개발자 API

개발자 API에서 기능을 선택하면 해당 기능의 명세를 보여줍니다. 응답 설명은 펼쳐서 확인할 수 있으며 OpenAPI 다운로드는 전체 명세를 제공합니다. 사용자 로그인은 각 사용자의 권한으로 호출하고, 서버 자동 연결은 별도로 만든 기기·서비스 계정의 권한으로 호출합니다.

개발자 API는 기존 Core·앱 업무 API를 iOS, Android, .NET 등의 외부 HTTP 클라이언트에 제공합니다. Nexia 클라이언트 SDK는 필수가 아닙니다. 외부연결의 개발자 API 화면에서 API 목록, OpenAPI 다운로드, JSON 요청 실행, 요청·응답 이력을 이용합니다. 기존 외부 API 연결은 Nexia에서 외부 서비스를 호출하는 별도 기능입니다.

권한·입력 검증·응답 정의는 해당 앱의 기존 코드에서 관리합니다. 호환되는 Core와 Manager/runtime을 적용하면 개발 실행과 설치된 릴리스의 카탈로그에 같은 API 구성이 적용됩니다. 개발 앱은 릴리스 제출 없이 사용할 수 있지만 실행 카탈로그가 승인된 상태여야 합니다. 선택된 실행에 아직 반영되지 않은 소스 변경은 호출할 수 없습니다.

앱과 돌아올 주소를 등록해 사용자 앱용 Client ID 하나를 발급받습니다. 여러 사용자가 같은 Client ID로 로그인하되 사용자별 토큰을 받습니다. API를 개별 선택할 필요 없이 실제 호출마다 로그인한 사용자의 현재 권한을 검사합니다. 사용자 로그인은 테넌트의 기존 로그인·SSO와 PKCE 인증 코드 흐름을 사용하고, 무인 장비는 별도 서비스 계정과 역할을 사용합니다. 관리 화면 접근 권한이 호출자의 업무·조직·레코드 권한을 대신하지 않습니다. 앱은 공통 Actor 계약을 사용하며 서비스 키를 숫자 User ID로 변환하면 안 됩니다. 개인 서명과 사람에게 배정된 업무는 User 로그인이 필요합니다.

Bearer 토큰으로 /api/v1/<업무 경로>를 호출합니다. /api/v1/openapi.json은 토큰의 접근 범위에 포함된 API를 반환합니다. 업무 권한은 API를 호출할 때 검사합니다. 기존 스키마를 재사용하고 원본 코드에서 검증 규칙과 응답 형식을 추출해 보충합니다. 동적 조건이나 타입이 없는 필드는 x-nexia-schema-gaps로 남을 수 있으며 실제 핸들러의 검증이 기준입니다. 호출 이력의 실제 검증 오류와 요청 ID를 확인하고, 결과가 불확실한 쓰기 요청은 자동 재시도하지 마세요.

앱 런타임 쓰기 요청(POST, PUT, PATCH, DELETE)에는 UUID 형식의 Idempotency-Key 헤더가 필요합니다. 새 작업에는 새 키를 만드세요. 결과가 불확실하면 호출 이력을 먼저 확인하고 같은 요청을 재시도할 때만 같은 키를 사용하며 자동 재시도하지 마세요. 키가 없거나 형식이 잘못되면 해당 헤더를 명시한 검증 오류와 422가 반환됩니다. Core 자체 API는 각 기능에 선언된 조건을 따릅니다. 개발자 지원 #50

앱 쓰기 결과를 바로 받지 못했다면 같은 API 클라이언트와 호출 주체의 유효한 토큰으로 GET /api/v1/__nexia/requests/{Idempotency-Key}를 조회하세요. data.request.status가 completed이면 data.request.http_status가 확정된 응답 상태입니다. 이 조회는 저장된 업무 응답 본문을 제공하지 않습니다. recovering이나 recovery_failed는 성공 또는 실패를 뜻하지 않으므로 새 키로 다시 실행하지 마세요. 조회 시 토큰에 허용된 원래 API 범위도 확인합니다.

앱이 반환하고 저장 영수증으로 확정된 오류는 HTTP 상태와 오류 코드를 유지합니다. 5xx에서는 내부 상세를 제외하고 유효한 오류 코드만 전달합니다. 이 동작에는 대응 Core와 앱 런타임이 모두 필요합니다.

앱 실행 결과가 확인되지 않았지만 런타임의 오류 상태를 수신했다면 응답의 data.upstream에 source: app_runtime과 실제 http_status가 표시됩니다. 이는 오류가 관찰된 계층과 상태이며, 업무 저장 결과를 확정하지는 않습니다.

외부 업무 API의 JSON 응답은 status(HTTP 상태), code, message, data, request_id를 포함합니다. 성공 시 기존 응답 본문은 data에 들어가며, 실패 시 code와 message를 확인합니다. 예를 들어 권한 조회 결과는 다음과 같습니다.

코드 예시
JSON
{"status":200,"code":"ok","message":"OK","data":{"permissions":{"people.worker.read":true,"people.worker.update":false}},"request_id":"요청 ID"}

이는 기존 /api/v1 응답 본문과 호환되지 않습니다. 연동 앱에서 기존 응답을 읽던 코드를 data 기준으로 변경하세요. OpenAPI 문서는 표준 형식을 유지하며, 본문이 없는 204 응답과 JSON이 아닌 응답은 그대로 반환합니다.

인증 정보는 테넌트와 접속 주소에 귀속되며 샌드박스 인증 정보로 운영 환경을 호출할 수 없습니다. 호환되는 Core·Manager/runtime 적용이 필요하고 앱 SDK의 새 릴리스는 필요하지 않습니다. 화면은 크기가 제한된 JSON 본문을 기록하고 인증 정보를 가립니다. 바이너리·스트리밍·용량 초과 본문은 기록되지 않은 사유를 표시합니다.

화면에서 여러 권한의 보유 여부를 확인하려면 사용자 또는 자동화 토큰으로 POST /api/v1/permissions/check를 호출하세요. permissions에는 확인할 권한 이름을 1~100개 넣습니다. 중복이나 빈 목록은 허용되지 않습니다. 필요하면 legal_entity, operating_unit에 해당 공개 ID를 지정합니다. 운영 조직을 지정할 때는 법인도 지정해야 합니다.

코드 예시
JSON
{"permissions":["people.worker.read","people.worker.update"]}

자동화 토큰의 권한 확인에는 선택한 호환 API 작업의 기본 권한과 같은 App에 속한 명시적 추가 필수 권한이 포함됩니다. 선언하지 않은 내부 권한이나 선택하지 않은 작업에만 속한 권한은 서비스 계정 역할에 있어도 false일 수 있습니다.

서비스 계정으로 ActorDirectory::activeByPublicIdForLegalEntity()를 사용하려면 directory.party.read 권한을 부여하고 API 연결에 호환되는 디렉터리 읽기 작업을 포함하세요. Core는 콜백마다 현재 권한과 법인 접근을 확인합니다. 이 디렉터리 권한은 기업 범위이므로 적절히 제한된 계정을 사용하고 단일 법인으로 제한된다고 가정하지 마세요. 다른 ActorDirectory 콜백은 서비스 계정에서 사용할 수 없습니다. Core 콜백 구현

응답의 data.permissions에는 요청한 항목별 결과만 포함됩니다. 알 수 없거나 토큰 범위 밖인 권한은 false입니다. 이 결과는 화면 표시를 돕는 정보이며, 업무 API 호출 시 서버가 현재 권한과 대상 레코드를 다시 검사합니다. 권한 조회를 먼저 호출할 필요는 없습니다.

웹 팝업과 Flutter·.NET 사용자 로그인

사용자 인증은 Nexia와 기업 SSO에서 진행하고 외부 앱에는 인증 코드와 토큰을 전달합니다. 기업 정책에 따라 기존 로그인 세션이 있어도 재인증·추가 인증·동의가 요구될 수 있습니다.

클라이언트로그인 화면복귀 방식
웹·Flutter Web사용자 클릭으로 팝업 또는 현재 창에서 이동등록한 웹 콜백, 앱 서버에서 코드 교환
.NET ASP.NET웹 로그인 흐름과 동일서버 콜백에서 토큰 보관
Flutter 모바일·.NET MAUI시스템 브라우저 또는 OS 인증 세션OS에 등록한 앱 콜백과 PKCE 검증자
Flutter·.NET 데스크톱시스템 브라우저등록한 앱 콜백 또는 루프백 수신 주소

모든 플랫폼은 /oauth/developer-api/authorize와 /oauth/developer-api/token을 사용합니다. 앱이 생성한 state, PKCE S256, 등록한 redirect_uri를 전달하고 콜백의 state와 iss를 검증하세요. HTTP 루프백 IP(127.0.0.1 또는 [::1]) 콜백은 데스크톱 수신기가 선택한 포트만 달라질 수 있습니다. 나머지 구성 요소와 HTTPS·앱 스킴·localhost 콜백은 정확히 일치해야 합니다. 코드 교환에는 실제 인증 요청에 사용한 콜백 URI를 그대로 보냅니다. 네이티브 앱에 client secret을 넣지 말고 토큰은 OS 보안 저장소에 보관하세요. 시스템 브라우저 사용 원칙은 RFC 8252를 따릅니다.

Flutter·.NET 연동 가이드에서 Flutter AppAuth의 OAuth 설정, .NET MAUI 콜백, 토큰 갱신·해지와 검증 범위를 확인할 수 있습니다. 새 사용자 앱의 Client ID는 해지 전까지 유지되며 사용자 로그인 권한은 90일 뒤 만료됩니다. 기존에 만료일이 있는 연결은 그 날짜를 유지하며 만료·해지된 연결을 되살리지 않습니다.

웹 팝업은 네트워크 요청 전에 사용자 클릭에서 직접 열고, 차단되면 전체 화면 이동으로 전환하세요. 회사 SSO의 COOP 정책으로 window.opener 연결이 끊길 수 있으므로 창 닫힘이나 창 메시지만으로 로그인 성공을 판단하면 안 됩니다. 콜백을 검증한 앱 서버의 세션·로그인 요청 상태를 확인하고, 완료·거부·취소·만료를 원래 화면에 반영하세요. 토큰은 팝업 메시지나 브라우저 영구 저장소로 전달하지 않고 앱 서버에서 관리할 수 있습니다.

이 흐름은 Nexia 업무 API의 사용자 권한 위임입니다. 별도의 OpenID Connect ID token·UserInfo 제공을 의미하지 않으며, 불투명한 액세스 토큰에서 사용자 프로필이나 역할을 추측하면 안 됩니다. Flutter·.NET에 전용 Nexia SDK가 없어도 같은 표준 HTTP 흐름을 구현할 수 있습니다.

관리형 App의 클라이언트 IP

HTTP 요청의 Laravel $request->ip()는 관리형 호스트가 확인한 클라이언트 주소가 있으면 반환합니다. null은 주소를 알 수 없는 상태로 보고 IP 제한 작업을 거부하세요. 요청 입력이나 서명되지 않은 전달 헤더를 대신 사용하지 마세요. 일치하는 Core와 App 런타임 업데이트가 필요하며, 다른 요청 경로에서는 확인된 주소가 없을 수 있습니다.

원본 위치: docs/developers/content/ko/building-apps/add-api-and-authorization.md