인증

모든 Nodaro API 요청은 Authorization 헤더의 Bearer 토큰으로 인증합니다. 내 서버가 내 계정으로 Nodaro를 호출할 때는 개인 API 토큰(ndr_…)을, 내 제품이 다른 Nodaro 사용자를 대신해 작동할 때는 OAuth 액세스 토큰(ndr_app_…)을, 셀프 호스팅 Community Edition 설치에서는 세션 JWT를 사용하세요.

Authorization: Bearer ndr_4f1c…

사용할 자격 증명

간단한 판단 기준: 서버에 자격 증명 한 세트만 필요하고 동의 화면이 필요 없다면 API 토큰을 사용하세요. 여러 고객이 각자 자기 계정에 대한 접근 권한을 내 앱에 줘야 한다면 OAuth를 사용하세요.

API 토큰은 Nodaro Cloud와 Business 에디션에서 사용할 수 있습니다. Community Edition에서는 같은 엔드포인트를 로그인한 세션의 액세스 토큰으로 호출하세요. 에디션을 참조하세요.

API 토큰 만들기

이 페이지에는 각 토큰의 이름, 접두사, 요청 한도, 마지막 사용 시각, 생성 시각이 나열됩니다. 토큰 옆의 스위치로 토큰을 켜거나 끄고, 휴지통 버튼으로 토큰을 삭제합니다.

API 토큰 규칙

• 계정당 토큰 최대 10개, 활성 여부와 관계없습니다. 비활성화한 토큰도 개수에 포함되므로, 자리를 비우려면 삭제하세요. 11번째 토큰은 400 limit_reached로 거부됩니다.
• 만료와 지출 한도 없음. 토큰은 비활성화하거나 삭제할 때까지 작동합니다. 토큰을 삭제하면 즉시 해지됩니다.
• 토큰은 나로서 작동합니다. 토큰이 하는 모든 호출은 내 계정으로 실행되며 내 크레딧을 사용합니다.
• 로그인 공급자 기준으로 다시 확인하지 않습니다. ID 공급자에서 계정이 제거되기 전에 만든 토큰은 해지할 때까지 계속 작동합니다. 모든 토큰을 영구적인 자격 증명으로 취급하세요.

토큰을 일부 워크플로로 제한

토큰을 워크플로 목록으로 제한할 수 있으며, 이 목록이 토큰의 워크플로 범위입니다. API 토큰 페이지에서 만든 토큰에는 범위가 없어서, 내가 소유한 모든 워크플로를 실행할 수 있습니다. workflowIds가 없는 토큰이 계정의 전체 접근 토큰입니다.

아래 엔드포인트로 토큰을 만들거나 업데이트할 때 workflowIds 필드로 최대 50개의 워크플로를 범위로 설정하세요. 범위 변경은 1분 안에 적용됩니다. 개인 공간에 있는 워크플로만 넣을 수 있으며, 워크스페이스에 있는 워크플로는 400 invalid_workflow로 응답합니다.

범위가 지정된 토큰은 해당 워크플로를 실행하기 위한 토큰입니다. 워크플로를 실행하고, 워크플로와 그 입력을 읽고, 그 실행을 추적할 수 있으며, 그 밖의 일은 할 수 없습니다.

• GET /v1/api/workflows, GET /v1/workflows, GET /v1/projects/:projectId/workflows는 해당 워크플로만 나열합니다. GET /v1/executions는 해당 워크플로의 실행만 나열합니다.
• GET /v1/api/schema, POST /v1/api/run, GET /v1/workflows/:id, GET /v1/workflows/:id/interface, POST /v1/workflows/:id/run, POST /v1/workflows/:id/render-final/estimate, GET /v1/workflows/:id/executions는 해당 워크플로에 대해서만 응답합니다.
• GET /v1/api/status/:execId, GET /v1/api/result/:execId, GET /v1/workflow-executions/:id와 그 /stream, /cancel 라우트는 해당 워크플로의 실행에 대해서만 응답합니다. 내 것이 아닌 실행에는 404로 응답합니다.
• 공개 갤러리, 모델 카탈로그와 노드 카탈로그처럼 로그인이 필요 없는 라우트는 토큰이 없을 때와 똑같이 응답합니다.

그 밖의 모든 요청은 403 forbidden으로 응답하며, 메시지는 “This API key is limited to specific workflows, and this request is outside them. Use a key without a workflow limit for anything else.”(이 API 키는 특정 워크플로로 제한되어 있으며, 이 요청은 그 범위를 벗어납니다. 그 밖의 작업에는 워크플로 제한이 없는 키를 사용하세요.)입니다. 다른 워크플로나 그 실행, 워크플로 편집이나 삭제, 직접 생성 라우트, 업로드, 작업, 게시된 앱, MCP, 중계 자격 증명으로 사용하는 경우가 모두 여기에 해당합니다. 요청은 아무것도 실행되기 전에 거부되므로, 크레딧이 예약되거나 청구되지 않습니다.

코드로 토큰 관리

이 네 라우트는 로그인한 세션에서만 작동하므로, API 토큰이 아니라 세션 JWT를 보내세요. 개인 API 토큰이나 OAuth 토큰은 403 forbidden으로 거부되며, 메시지는 “API token management is only available from a logged-in session”(API 토큰 관리는 로그인한 세션에서만 가능)입니다. Community Edition 설치에서는 생성 라우트와 목록 라우트가 required_edition: "business"와 함께 403 edition_required로 응답합니다.

토큰을 하나의 워크스페이스에 연결하려면 토큰을 워크스페이스에 연결을 참조하세요.

토큰 보내기

GET /v1/me는 유효한 토큰에 연결된 계정을 반환하므로, 토큰을 확인하는 가장 빠른 방법입니다. 토큰이 없거나, 유효하지 않거나, 해지되었으면 401 unauthorized로 응답합니다.

curl https://app.nodaro.ai/v1/me \
  -H "Authorization: Bearer $NODARO_API_KEY"

{
  "data": {
    "id": "5bf0d884-47b1-468e-a7b2-2433f957b267",
    "email": "ada@example.com",
    "displayName": "Ada",
    "avatarUrl": null,
    "tier": "pro",
    "isAdmin": false
  }
}

import { createClient, StaticTokenAuth } from '@nodaro/sdk'

const client = createClient({
  baseUrl: 'https://app.nodaro.ai',
  auth: new StaticTokenAuth(process.env.NODARO_API_KEY!),
})

const me = await client.me()
console.log(me.email, me.tier)

nodaro auth login --token "$NODARO_API_KEY"
nodaro auth status

조직에 속한 계정에서는 같은 응답에 계정이 속한 조직과 워크스페이스도 담깁니다. 워크스페이스와 조직을 참조하세요.

SDK는 인증 공급자에게서 토큰을 받으므로, 토큰을 어떻게 찾을지 직접 선택할 수 있습니다.

CLI는 토큰을 파일 모드 0600으로 ~/.config/nodaro/config.json에 저장합니다. 셀프 호스팅 설치용 두 번째 로그인을 유지하려면 --profile과 --base-url을 추가하세요. 예: nodaro auth login --profile local --base-url http://localhost:3000.

OAuth 액세스 토큰

각 사용자가 자신의 Nodaro 계정을 내 제품에 연결하게 할 때는 OAuth를 사용하세요. 내 서버가 인증 코드를 ndr_app_으로 시작하는 액세스 토큰으로 교환합니다. 토큰의 유효 기간은 90일이며, 갱신 토큰은 없습니다. 토큰이 만료되면 사용자를 동의 화면으로 다시 안내하세요.

OAuth 토큰에는 사용자가 허용한 범위만 담깁니다. 토큰에 없는 범위가 필요한 라우트는 403 insufficient_scope로 응답하며, 오류의 missingScope에 해당 범위가 표시됩니다. 대부분의 API 통합에 필요한 범위는 다음과 같습니다.

개인 API 토큰과 세션 JWT에는 범위가 없으며, 내 계정으로 작동합니다. 전체 흐름, 모든 범위, 동의 화면은 OAuth 앱에서 확인하세요.

로그인한 세션이 필요한 라우트

몇몇 라우트는 Nodaro 웹 앱 전용이며, API 토큰과 OAuth 토큰을 모두 거부합니다.

코드로 워크플로를 만들려면 워크플로 엔드포인트, SDK 또는 MCP 서버를 사용하세요.

클라이언트 식별

X-Nodaro-Client 헤더를 보내면 Nodaro가 그 값을 요청으로 생성되는 모든 작업의 출처로 기록합니다.

X-Nodaro-Client: sdk/1.10.0

인식되는 형식은 sdk/<version>, cli/<version>, extension/<name> 세 가지뿐입니다. 이 헤더는 인증되지 않으므로 그 밖의 값은 무시됩니다. @nodaro/sdk와 @nodaro/cli가 이 헤더를 자동으로 보내므로, REST API를 직접 호출할 때만 필요합니다. 생략해도 괜찮습니다. 그러면 해당 작업은 일반 API 호출로 기록됩니다.

브라우저에서 호출할 때는 이 헤더를 보내지 마세요. 브라우저의 Origin 헤더가 이미 사이트를 알려 주며, Nodaro는 그 값을 우선합니다. SDK는 브라우저에서 실행될 때 이 헤더를 자동으로 생략합니다.

토큰은 서버에 보관

브라우저 코드에 있는 토큰은 개발자 도구만 있으면 누구나 읽을 수 있고, 내 크레딧을 쓸 수 있습니다. 토큰은 서버 라우트, 엣지 함수 또는 플랫폼의 비밀 저장소에 두고, 브라우저는 내 서버와만 통신하게 하세요.

Browser  ->  your server (holds NODARO_API_KEY)  ->  Nodaro API

예를 들어 Next.js에서는 라우트 핸들러에서 NEXT_PUBLIC_ 접두사가 없는 환경 변수로 토큰을 읽으세요. OAuth 토큰으로 브라우저에서 Nodaro를 호출한다면, 개발자 앱의 허용된 출처에 사이트의 출처를 추가하세요.

토큰으로 셀프 호스팅 설치 연결

워크플로 범위가 없는 개인 API 토큰은 셀프 호스팅 설치의 생성 작업을 Nodaro Cloud에서 실행하는 가장 간단한 방법이기도 합니다. 셀프 호스팅 설치에서 NODARO_CLOUD_URL을 Nodaro Cloud 주소로, NODARO_API_KEY를 내 토큰으로 설정하세요. 그러면 모든 생성이 Nodaro Cloud에서 실행되고 토큰 계정으로 청구되며, OAuth 연결은 필요하지 않습니다. Nodaro Cloud에 연결을 참조하세요.

결제 계정이 하나인 배포

일부 배포에는 모든 사용자의 비용을 내는 결제 계정이 하나만 있습니다. 이런 배포에서는 다음과 같습니다.

• 결제 계정만 토큰을 만들 수 있습니다. 다른 사용자는 403 api_tokens_payer_only를 받으며, 기존 토큰은 소유자가 계속 목록에서 보고 해지할 수 있습니다.
• 설정에 API 토큰 카드가 표시되지 않습니다. 결제 계정은 /settings/api를 직접 엽니다.
• 토큰이 하는 모든 호출은 배포의 공동 잔액에서 지불됩니다.
• 토큰으로는 그 공동 잔액을 읽을 수 없습니다. 결제 계정의 토큰으로 잔액을 읽으면 403 payer_balance_jwt_only로 응답하고, 배포 결제 라우트는 403 payer_required로 응답합니다.

오류

모든 오류는 같은 응답 형식을 사용합니다. 전체 목록은 오류를 참조하세요.