인증 | Minds

Minds 연구 API에는 API 키 또는 승인된 OAuth 권한이 필요합니다. 공개 페이지와 검색용 문서는 로그인 없이 읽을 수 있습니다.

API 키 받기

Minds 계정에 로그인합니다.
설정 → API 키로 이동합니다.
새 API 키 생성을 클릭합니다.
API 키를 즉시 복사합니다(다시 볼 수 없습니다!).

API 키는 minds_로 시작하며 다음과 같은 형식입니다: minds_0000111122223333444455556666777788889999aaaabbbb

API 키 사용하기

모든 요청의 Authorization 헤더에 API 키를 포함시킵니다:

Authorization: Bearer minds_your_api_key_here

예제 요청

curl -X GET "https://getminds.ai/api/v1/api-keys" \
  -H "Authorization: Bearer minds_your_api_key"

보안 모범 사례

키를 비밀로 유지하기

절대 API 키를 버전 관리 시스템에 커밋하지 마세요.
절대 공개 포럼이나 채팅에서 키를 공유하지 마세요.
키를 환경 변수나 안전한 금고에 저장하세요.
보안을 위해 정기적으로 키를 교체하세요.

환경 변수 사용하기

# Set your key as an environment variable
export MINDS_API_KEY="minds_your_api_key_here"

# Use it in requests
curl -X GET "https://getminds.ai/api/v1/api-keys" \
  -H "Authorization: Bearer $MINDS_API_KEY"

키를 정기적으로 교체하기

키가 유출된 것으로 의심되는 경우:

새 API 키를 생성합니다.
애플리케이션을 새 키로 업데이트합니다.
이전 키를 삭제합니다.

인증된 사용자 식별하기

API 키가 유효한지 확인하고 어떤 계정에 속하는지 식별합니다:

GET /api/v1/auth/me

응답:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

API 키와 연결된 사용자 ID를 반환합니다. 시작 시 또는 키를 교체한 후 자격 증명을 확인하는 데 유용합니다. 키가 없거나 유효하지 않은 경우 401 Unauthorized를 반환합니다.

API 키 관리하기

API 키 목록 보기

GET /api/v1/api-keys

메타데이터와 함께 API 키 목록을 반환합니다(실제 키 값은 반환되지 않음):

[
  {
    "id": "key-id",
    "name": "prod",
    "createdAt": "2025-12-10T12:00:00.000Z",
    "lastUsedAt": "2025-12-10T13:00:00.000Z"
  }
]

새 API 키 생성하기

POST /api/v1/api-keys

헤더:

Content-Type: application/json

요청 본문 (선택 사항):

{
  "name": "prod"
}

선택적 name 필드는 키에 대한 사람이 읽을 수 있는 레이블입니다(문자열, 1–100자). 목록 엔드포인트와 설정 UI에서 키를 식별하는 데 도움이 됩니다. 공백은 제거되며, 빈 값이나 누락된 값은 null로 저장됩니다. 빈 요청 본문도 허용되며 이름 없는 키를 생성합니다.

응답에는 실제 키가 포함됩니다(이때만 볼 수 있습니다):

{
  "id": "new-key-id",
  "name": "prod",
  "key": "minds_0000111122223333444455556666777788889999aaaabbbb",
  "createdAt": "2025-12-10T12:00:00.000Z"
}

이름이 있는 예제

curl -X POST "https://getminds.ai/api/v1/api-keys" \
  -H "Authorization: Bearer minds_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod"}'

⚠️ 중요: key 값을 즉시 저장하세요! 다시 가져올 수 없습니다.

API 키 삭제하기

DELETE /api/v1/api-keys/{keyId}

성공 시 빈 본문과 함께 204 No Content을 반환합니다.

인증 오류

401 권한 없음

API 키가 누락되었거나 유효하지 않습니다.

{
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Invalid or missing API key"
}

해결 방법:

Authorization 헤더가 포함되었는지 확인하세요.
API 키가 정확한지 확인하세요.
Bearer 접두사를 사용하고 있는지 확인하세요.
이전 키가 삭제된 경우 새 키를 생성하세요.

요금제 기반 접근

API 접근은 유료 요금제에서 지원되며 제품에 표시되거나 계약으로 합의된 리소스, 응답 및 워크스페이스 한도의 적용을 받습니다. 한도를 코드에 고정하지 말고 구조화된 PLAN_LIMIT 및 plan_limited 응답을 처리하세요. Starter 요금제는 API 페이로드에서 "premium"으로 표시됩니다.

요금제 보기

에이전트 읽기 전용 연결

에이전트는 auth.md를 통해 읽기 권한을 요청할 수 있습니다. 지정된 인증된 계정으로 로그인하고, 에이전트가 표시하는 6자리 코드를 입력한 뒤 화면의 권한을 승인하세요. 요청은 10분 후 만료됩니다.

초기 등록 자격 증명은 자체 상태만 조회할 수 있습니다. 승인 후 에이전트는 지원되는 Mind, 오디언스 및 연구를 읽는 제한된 OAuth 토큰을 받습니다. 연구 변경, 유료 작업 시작, API 키 생성 또는 계정 관리는 할 수 없습니다. 설정에서 OAuth 연결을 삭제하면 접근 권한이 취소됩니다.

MCP에는 보호된 리소스 메타데이터를 사용하세요. 공개 페이지를 읽는 데에는 권한이 필요하지 않습니다.