인증

자신의 백엔드나 자동화에는 API 키를 사용하세요. 애플리케이션이 다른 Make Agent Fast 사용자에게 접근 권한을 요청할 때는 OAuth를 사용합니다. 두 자격 증명 모두 같은 /api/v1 리소스를 호출하며 동일한 범위, 요금제 권한, 테넌트 격리, 요청 한도를 따릅니다.

API 키#

공개 API 키를 만들고 사용하려면 활성 유료 요금제가 필요합니다.

1. 대시보드 → 설정 → 개발자를 엽니다.
2. Production lead export처럼 서비스와 환경을 식별할 이름을 입력합니다.
3. 서비스에 필요한 최소 범위를 선택합니다.
4. 30일, 90일, 1년 또는 만료 없음 중에서 선택합니다.
5. 키를 만들고 maf_live_... 값을 즉시 복사합니다.

Make Agent Fast는 복구 가능한 평문 대신 SHA-256 해시를 저장합니다. 대시보드는 이후 안전한 접두사, 범위, 만료, 마지막 사용 시각, 폐기 상태를 표시합니다.

Authorization: Bearer maf_live_...

서버 코드에서 헤더를 전송하세요.

curl --fail-with-body https://makeagent.fast/api/v1/me \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Accept: application/json"

자격 증명이 없으면 401 authentication_required, 잘못되었거나 만료·폐기된 키는 401 invalid_api_key를 반환합니다. 키 소유 계정에 활성 유료 요금제가 없으면 403 subscription_required를 반환합니다.

키 교체 또는 폐기#

이전 키를 폐기하기 전에 대체 키를 만드세요. 대체 키를 배포하고 실제 요청을 보내 x-request-id를 확인한 다음 이전 키의 폐기를 클릭합니다. 폐기는 즉시 적용되며 되돌릴 수 없습니다.

기존 키의 범위와 만료를 넓힐 수 없습니다. 권한 변경을 명시적으로 남기려면 대체 키를 만드세요.

OAuth 애플리케이션#

OAuth는 다른 Make Agent Fast 사용자가 소유한 계정을 연결하는 소프트웨어를 위한 기능입니다. PKCE(S256)가 있는 Authorization Code를 사용하며 클라이언트 시크릿을 발급하거나 요구하지 않습니다. 클라이언트 ID는 공개 값이지만 승인 코드, 액세스 토큰, 리프레시 토큰, PKCE 검증자는 민감합니다.

1. 애플리케이션 등록#

대시보드 → 설정 → 개발자 → OAuth 애플리케이션을 엽니다. 다음을 추가하세요.

• 2~100자의 애플리케이션 이름
• 정확한 리디렉션 URL 1~10개
• 애플리케이션이 요청할 수 있는 최대 범위

프로덕션 리디렉션 URL은 HTTPS를 사용해야 하며 자격 증명이나 프래그먼트를 포함할 수 없습니다. 승인과 토큰 교환에서 전체 URI가 등록 값과 정확히 일치해야 합니다. 새 애플리케이션은 pending 상태이며 검토 후 approved가 되어야 승인이 작동합니다.

2. PKCE 값 생성#

각 승인 시도마다 새 검증자를 만들고 state와 같은 보호된 단기 세션에 보관합니다.

import { createHash, randomBytes } from "node:crypto";

const verifier = randomBytes(48).toString("base64url");
const challenge = createHash("sha256").update(verifier).digest("base64url");
const state = randomBytes(24).toString("base64url");

검증자는 URL 안전 PKCE 문자 43~128자로 구성되어야 합니다. code_challenge_method=S256만 허용됩니다.

3. 사용자 동의로 리디렉션#

https://makeagent.fast/oauth/authorize
  ?client_id=maf_app_...
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
  &response_type=code
  &scope=sites%3Aread%20leads%3Aread
  &state=RANDOM_STATE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

사용자가 로그인하고 요청 범위를 검토한 뒤 접근을 허용하거나 거부합니다. 성공하면 Make Agent Fast는 정확히 등록된 URI로 code와 원래 state를 전달합니다. 거부하면 error=access_denied와 제공된 경우 원래 state를 전송합니다.

콜백의 state가 해당 브라우저 세션에 저장한 값과 정확히 일치하지 않으면 거부하세요.

4. 승인 코드 교환#

승인 코드는 10분 뒤 만료되며 한 번만 사용할 수 있습니다.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode "redirect_uri=https://app.example.com/oauth/callback" \
  --data-urlencode "code_verifier=$PKCE_VERIFIER"

{
  "access_token": "maf_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "maf_refresh_...",
  "scope": "sites:read leads:read"
}

액세스 토큰은 1시간, 리프레시 토큰은 더 일찍 교체되거나 폐기되지 않으면 최대 90일 동안 유효합니다.

5. 리프레시 토큰 교체#

성공적인 갱신은 제출한 리프레시 토큰과 이전 액세스 토큰을 모두 폐기한 뒤 새 쌍을 반환합니다. 이전 응답 상태를 버리기 전에 새 쌍을 원자적으로 저장하세요.

curl --fail-with-body https://makeagent.fast/api/oauth/token \
  -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=maf_app_..." \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

승인 코드나 교체된 리프레시 토큰을 다시 사용하면 invalid_grant를 반환합니다. OAuth 토큰 엔드포인트는 공개 API 오류 형식 대신 OAuth 스타일의 { "error", "error_description" } 응답을 사용하며 클라이언트와 호출자당 분당 30개의 토큰 요청을 허용합니다.

브라우저 코드에서 관리 요청을 인증하지 마세요#

React 클라이언트 컴포넌트, 정적 JavaScript, 모바일 웹, Webflow, Framer, Wix 또는 Shopify Liquid에 비밀 API 키, 액세스 토큰, 리프레시 토큰을 넣지 마세요. 인증된 백엔드를 사용합니다. 공개 웹사이트 임베드는 관리 API 자격 증명이 아니라 비밀이 아닌 사이트 슬러그와 오리진 허용 목록을 사용합니다.

자격 증명 및 토큰, 범위 및 오류, API 빠른 시작을 참고하세요.