API 참조
현재 Tungsto API에 인증
계정, 청구 및 서버 엔드포인트와 통합하기 전에 지원되는 세션 쿠키 및 CSRF 계약을 이해하십시오.
시작하기 전에
- 기존 계정과 HTTPS를 통해 실행 중인 계정 서비스에 대한 액세스.
- 요청 간에 세션 쿠키를 보존하는 클라이언트.
- 변경의 경우 동일한 활성 세션과 연결된 CSRF 토큰.
지원되는 인증 방법 사용
보호된 API 경로는 로그인으로 설정된 계정 세션을 사용합니다. 세션 쿠키 이름은 __Host-tungsto-session이며 Secure 및 HttpOnly로 표시됩니다. 두 번째 쿠키 __Host-tungsto-csrf는 요청 검증을 지원합니다. 계정 변경에는 세션 쿠키 외에도 해당 세션과 일치하는 x-csrf-token 헤더가 필요합니다.
SSH 및 API 키 화면은 범위가 지정된 키를 생성, 나열, 취소합니다. Authorization: Bearer 다음에 일회용 키를 보내세요. 읽기 범위는 GET /api/v1/servers, 서버 세부 정보, /api/v1/orders를 허용합니다. 서버 범위는 서버, 서버 세부 정보, /api/v1/network를 허용합니다. 청구 범위는 GET /api/v1/ledger.를 허용합니다. 브라우저 세션이 있어도 모든 API 키 변경은 거부됩니다. 비밀번호 변경이나 계정 복구는 기존 키를 취소합니다. 이 로컬 미리보기를 기반으로 무인 프로덕션 하드웨어나 결제 자동화를 구축하지 마세요.
세션 설정 및 확인
위 요청은 필드 이름만 표시합니다. 자격 증명은 자신의 클라이언트에서 안전하게 제공하십시오. 공유 예제나 진단 출력에 실제 비밀번호를 저장하지 마십시오. 브라우저의 요청은 동일한 사이트에 있어야 합니다. 다른 출처를 명시하는 Origin 헤더는 거부됩니다.
- 사용자 이름과 비밀번호를 포함한 JSON POST 요청을 /api/v1/auth/login으로 보내세요. 성공적인 응답에서 반환된 Set-Cookie 값을 클라이언트의 보호된 쿠키 저장소에 보관하세요.
- JSON 응답에서 반환된 csrfToken을 해당 세션과 함께 유지하세요. 한 로그인의 토큰을 다른 쿠키와 혼합하지 마세요.
- 쿠키와 함께 GET /api/v1/me을(를) 호출하여 계정을 확인하십시오. 응답에는 username, balanceUsd 및 csrfToken이 포함됩니다.
- 보호된 변경의 경우 세션 쿠키, Content-Type: application/json, x-csrf-token을 전송하십시오. 엔드포인트가 요구할 때 Idempotency-Key를 포함하십시오.
- 클라이언트가 완료되면 POST /api/v1/auth/logout을(를) 사용하여 세션을 종료하세요.
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}세션 만료 및 확인 오류 처리
성공적인 계정 복구는 비밀번호를 변경하고 기존 세션을 취소하며 교체용 복구 코드를 발급합니다. 이전 쿠키를 사용하는 클라이언트는 다시 인증해야 합니다. 서비스는 세션도 만료시키므로 이전에 성공한 연결이 무제한 자격 증명이 되지 않습니다.
| 응답 | 의미 | 다음 작업 |
|---|---|---|
| 401 authentication_required | 유효한 계정 세션을 찾을 수 없습니다. | 다시 로그인하고 새 쿠키를 유지하십시오. |
| 401 session_invalid | 세션 및 CSRF 쿠키가 함께 확인되지 않습니다. | 혼합 쿠키를 재사용하는 대신 새 로그인을 시작하세요. |
| 403 csrf_failed | 변경 요청에 일치하는 확인 토큰이 없습니다. | 세션 정보를 다시 로드하고 현재 토큰을 사용하십시오. |
| 403 origin_rejected | 제공된 Origin이 요청의 Origin과 다릅니다. | 지원되는 동일 사이트 컨텍스트에서 요청을 실행하세요. |
| 429 rate_limited | 인증 시도가 너무 많았습니다. | 다시 시도하기 전에 기다리십시오. 계속 재시도하지 마십시오. |
통합을 현재 계약 내에서 유지하십시오
보안 화면에는 GET /api/v1/sessions을(를) 통한 활성 세션이 나열되며 DELETE /api/v1/sessions/:id.을(를) 통해 소유한 세션을 취소합니다. 키 화면에는 API 키가 나열되고 취소됩니다. OAuth 흐름은 없습니다. 등록 및 복구는 대화형 계정 액세스 작업이지 서비스 계정 메커니즘의 대체 수단이 아닙니다. 한 사람의 세션 쿠키를 여러 도구나 사용자에게 배포하지 마십시오.
인증 성공을 받으면 계정 액세스를 확인하지만 모든 외부 작업이 가능한 것은 아닙니다. 암호화폐 결제에는 연결된 공급자가 필요하고, 물리적 서버 작업에는 운영자가 대기 중인 요청을 실행해야 합니다. 성공적인 응답을 완료된 실제 작업으로 해석하기 전에 엔드포인트별 결과 및 재시도 동작에 대한 운영 가이드를 읽으세요.