커넥트 API 레퍼런스

엔드포인트별 요청 파라미터, 응답 필드, 오류 코드를 정리했습니다.
단계별 설명은 가이드에서, 직접 실행할 수 있는 도구는 샌드박스에서 확인할 수 있습니다.

기본 정보

인증 방식

대상 지정 파라미터

/me, /unlink, /subscription, /usage는 대상 사용자와 서비스를 아래 파라미터로 지정합니다.
GET 요청은 쿼리 파라미터로, POST 요청은 본문 필드로 전달합니다(user_id, service_id 표기도 지원).

요청 한도와 유효 기간

키와 토큰의 접두사

승인 화면

브라우저에서 해당 주소로 이동합니다. 서버 간 요청으로 처리하지 않습니다.
사용자가 로그인 후 승인하면 등록된 redirect_uri로 인가 코드가 전달됩니다.

• AI Market 계정이 없는 사용자는 로그인 화면에서 회원가입(이메일, 카카오, 네이버, Google)을 마친 후 승인 화면으로 돌아옵니다.
• 승인 화면에는 서비스 이름(service_id를 생략한 경우 크리에이터 이름), 제공되는 정보, 돌아갈 주소가 표시됩니다.
• 이미 같은 항목에 동의한 사용자는 승인 화면 없이 바로 인가 코드가 전달됩니다. 요청한 scope가 늘어난 경우 승인 화면이 다시 표시됩니다.
• 승인 화면에는 지금 로그인한 AI Market 계정이 표시되며, 사용자는 [다른 계정으로 진행]으로 로그아웃 후 다른 계정으로 로그인해 같은 요청을 이어 갈 수 있습니다.

결과(리다이렉트)

오류 화면 코드(리다이렉트 없이 화면에 표시)

토큰 발급과 갱신

서버에서 요청을 전송합니다. Content-Type은 application/x-www-form-urlencoded입니다.
grant_type 값에 따라 두 가지 요청을 처리합니다.

grant_type=authorization_code: 인가 코드 교환

grant_type=refresh_token: 토큰 갱신

client_id와 client_secret은 폼 필드 대신 Authorization: Basic base64(client_id:client_secret) 헤더로 전달할 수 있습니다.

응답 200

{ "access_token": "nxa_…", "token_type": "Bearer", "expires_in": 2592000, "refresh_token": "nxr_…", "refresh_token_expires_in": 15552000, "scope": "profile email name" }

오류

토큰 폐기

응답은 200 {"ok": true}입니다. 알 수 없는 토큰이나 다른 키에서 발급된 토큰도 200으로 응답하며, 토큰의 존재 여부는 노출하지 않습니다.
클라이언트 인증에 실패한 경우에만 401 invalid_client로 응답합니다.

토큰을 폐기해도 사용자와의 연결은 유지됩니다. 연결까지 끊으려면 연결 끊기를 사용하세요.

사용자 정보 조회

AI Market 로그인으로 연결된 사용자의 정보를 조회합니다.
로그인 직후에는 Authorization: Bearer {access_token} 헤더로 호출하고, 이후에는 API 키와 userId로 호출할 수 있습니다.

{ "id": "22270e30-…", "mode": "live", "scope": "profile email name", "email": "user@example.com", "emailVerified": true,
  "name": "홍길동", "nickname": "gildong", "profileImageUrl": "https://ai-market.co.kr/nexa/avatars/…", "connectedAt": "2026-10-06T10:12:44+09:00" }

오류: 401 invalid_token(접근 토큰 누락·만료·폐기), 401 invalid_client(API 키 불일치 또는 키 비활성), 403 user_not_connected(연결되지 않은 사용자), 400 invalid_request(userId 누락 또는 형식 오류), 429.

연결 끊기

사용자와 서비스의 연결을 끊습니다. 해당 사용자에게 발급된 접근 토큰과 갱신 토큰이 모두 폐기됩니다.
API 키와 userId로 호출하며, 요청 본문은 JSON 또는 폼 인코딩 형식을 지원합니다.

응답은 200 {"id": "22270e30-…"}이며, id는 연결을 끊은 사용자의 ID입니다.
연결이 끊긴 사용자에 대한 요청은 403 user_not_connected로 응답합니다. 이미 연결이 끊긴 사용자의 연결 끊기를 다시 요청한 경우에도 동일합니다.
사용자가 다시 로그인하면 승인 화면에서 동의를 다시 받습니다.

오류: 401 invalid_client(API 키 불일치 또는 키 비활성), 403 user_not_connected(연결되지 않은 사용자), 400 invalid_request(userId 누락 또는 형식 오류), 401 invalid_token(접근 토큰으로 호출한 경우. 토큰 누락·만료·폐기), 429.

연결 끊김 조회

이 키에서 since 이후에 끊긴 연결을 끊긴 시각 순으로 조회합니다. 사용자가 AI Market 마이페이지에서 연결을 끊었거나 탈퇴한 경우를 서비스가 주기적으로 확인하는 용도입니다.
API 키로만 호출할 수 있으며(접근 토큰 불가), 대상 사용자는 지정하지 않습니다.

{ "mode": "live", "since": "2026-10-06T09:00:00+09:00",
  "items": [ { "userId": "22270e30-…", "disconnectedAt": "2026-10-06T10:12:44.183+09:00", "by": "user" } ],
  "hasMore": false, "next": "2026-10-06T10:12:44.183+09:00" }

다시 연결된 사용자는 목록에서 제외됩니다. 같은 사용자가 끊었다가 다시 연결하면 그 사이의 끊김은 조회되지 않습니다.

오류: 401 invalid_client(API 키 불일치, 키 비활성, 또는 접근 토큰으로 호출), 400 invalid_request(since·limit 형식 오류), 429.

구독 확인

API 키와 userId, serviceId로 해당 사용자의 구독 상태를 조회합니다.
구독 상태는 요청 시점에 실시간으로 확인합니다.

오류: 401 invalid_client(API 키 불일치 또는 키 비활성), 403 user_not_connected(연결되지 않은 사용자), 403 invalid_service(본인이 등록한 서비스가 아니거나 삭제된 서비스), 400 invalid_request(userId·serviceId 누락 또는 형식 오류), 401 invalid_token(접근 토큰으로 호출한 경우. 토큰 누락·만료·폐기), 429.

사용량 조회

API 키와 userId, serviceId로 해당 사용자의 사용량과 잔액을 조회합니다.
월 제공량(토큰·크레딧)이 설정된 구독형 서비스에서 유효한 구독이 있는 경우에만 성공합니다.

오류: 400 usage_not_enabled(월 제공량이 설정되지 않은 서비스), 403 subscription_inactive(유효한 구독이 없는 경우. error_description에 현재 status가 포함됩니다.), 403 user_not_connected(연결되지 않은 사용자), 403 invalid_service(본인이 등록한 서비스가 아니거나 삭제된 서비스), 400 invalid_request(userId·serviceId 누락 또는 형식 오류), 401 invalid_client(API 키 불일치 또는 키 비활성), 401 invalid_token(접근 토큰으로 호출한 경우. 토큰 누락·만료·폐기), 429.

사용량 보고

API 키로 호출하며, userId로 지정한 사용자의 잔액에서 amount만큼 차감합니다.
요청 본문은 JSON 또는 폼 인코딩 형식을 지원합니다.

curl -X POST https://ai-market.co.kr/api/v1/connect/usage \
  -u nxc_xxxxx:nxs_xxxxx -H "Content-Type: application/json" \
  -d '{"userId": "22270e30-…", "serviceId": "68f5f1e7-…", "amount": 150, "idempotencyKey": "req-20260922-0001"}'

응답 형식은 사용량 조회와 동일하며, report 객체가 추가됩니다.

사용량은 월 제공량 → 추가 구매분 순서로 차감됩니다. 오류: 400 invalid_request(userId·serviceId 누락 또는 형식 오류, amount 누락·0 이하·정수가 아닌 값·상한 초과, idempotencyKey 또는 memo 길이 초과), 400 usage_not_enabled(월 제공량이 설정되지 않은 서비스), 403 subscription_inactive(유효한 구독이 없는 경우. error_description에 현재 status가 포함됩니다.), 403 user_not_connected(연결되지 않은 사용자), 403 invalid_service(본인이 등록한 서비스가 아니거나 삭제된 서비스), 401 invalid_client(API 키 불일치 또는 키 비활성), 401 invalid_token(접근 토큰으로 호출한 경우. 토큰 누락·만료·폐기), 429.

객체 사전

subscription 객체(구독 확인)

usage 객체(잔액 요약)

usage 객체의 값은 모두 요청에서 지정한 사용자 한 명의 구독을 기준으로 합니다.

오류 형식과 코드

토큰, 사용자 정보, 구독, 사용량 API의 오류 응답에는 error와 error_description 두 필드가 포함됩니다.
승인 화면의 오류는 화면에 코드로 표시됩니다(승인 화면).

{ "error": "invalid_grant", "error_description": "code expired or already used" }

401 응답에는 WWW-Authenticate 헤더가 포함됩니다.
invalid_client는 보안상 세부 인증 실패 원인을 구분하지 않습니다.

테스트 키 응답 규칙

테스트 키(nxc_test_…)와 테스트 키로 발급한 토큰은 실제 구독과 결제 대신 샌드박스 데이터로 응답합니다.
요청 형식은 운영 키와 동일하며, 다음 항목만 다릅니다.