# API 토큰 | Procurize.AI

**Procurize.AI 작업 공간에 대한 안전한 프로그래매틱 접근을 위해 API 토큰을 생성, 관리 및 사용하세요.**

> **적용 대상:** Procurize.AI 대시보드 → 설정 → 토큰  
> **이용 가능한 플랜:** Business & Enterprise 플랜  
> **필요한 역할:** 관리자 또는 유지보수자

## 개요

API 토큰은 Procurize.AI 플랫폼에 대한 안전하고 프로그래매틱한 접근을 가능하게 합니다. 토큰을 사용해 내부 시스템과 Procurize.AI를 연동하거나 워크플로를 자동화하고, 플랫폼 위에 맞춤형 애플리케이션을 구축할 수 있습니다.

**주요 특징:**

- 토큰은 **생성자를 위한 모든 권한**을 상속합니다
- 토큰은 **조직 범위**이며 API 호출 시 `org`를 지정할 필요가 없습니다
- 무제한으로 토큰을 생성할 수 있습니다
- 토큰에 **만료일**을 지정하거나 무제한으로 설정할 수 있습니다
- 토큰은 **비활성화**했다가 필요 시 **재활성화**할 수 있습니다

> 🔒 **보안 주의:** Procurize.AI는 토큰 값을 저장하지 않고 **해시만** 보관합니다. 생성 직후 토큰을 복사하여 안전하게 저장해야 합니다. 다시는 표시되지 않습니다.

## 토큰 관리 패널 접근 방법

1. **대시보드** → **설정** → **토큰** 탭으로 이동합니다.  
2. 토큰 관리 패널에 현재 조직에 연결된 개인 토큰이 표시됩니다.

![API 토큰 패널](/images/docs/api-tokens-panel.png)

> **필요 권한:** **관리자** 또는 **유지보수자** 역할을 가진 사용자만 이 패널에 접근할 수 있습니다. 자세한 역할 정의는 [권한 개요](/what-user-permissions-does-procurize-have/)를 참고하세요.

## 새 토큰 생성

1. 토큰의 목적을 식별할 **이름**을 입력합니다.  
2. **만료 기간**을 선택합니다:
   - 1개월
   - 3개월
   - 1년
   - **만료 없음** (무제한)

3. **"생성"** 버튼을 클릭합니다.

### 중요 – 토큰을 즉시 복사

생성 후 토큰 값은 **한 번만** 표시됩니다 – 바로 복사하여 비밀번호 관리자나 환경 변수 등에 안전하게 저장하세요.

![새 API 토큰](/images/docs/new-api-token.png)

> ⚠️ **다시 토큰 값을 확인할 수 없습니다.** Procurize.AI는 검증을 위해 해시만 저장합니다. 토큰을 분실하면 즉시 폐기하고 새 토큰을 생성해야 합니다.

## 기존 토큰 관리

토큰 패널에는 모든 생성된 토큰이 다음 정보를 포함해 리스트로 표시됩니다:

- 이름
- 접미사
- 생성 날짜
- 만료 날짜 (또는 “-”)
- 상태: **활성** 또는 **비활성**

### 토큰 비활성화 / 재활성화

- **비활성화** – 토큰을 일시적으로 사용 중지합니다. 필요 시 재활성화할 수 있습니다.  
- **재활성화** – 이전에 비활성화된 토큰을 다시 활성 상태로 복원합니다.

> 💡 비활성화는 토큰을 삭제하지 않고 통합을 일시 중단할 때 유용합니다.

### 토큰 폐기

- **폐기** – 토큰을 영구 삭제합니다. 이 작업은 복구할 수 없습니다.  
- 토큰을 분실한 경우 즉시 폐기하고 새 토큰을 생성하세요.

## API 토큰 사용 방법

### 기본 URL 및 인증

| 매개변수 | 값 |
|-----------|-------|
| **기본 URL** | `https://api.procurize.com` |
| **인증 방법** | 헤더를 통한 API 키 |
| **헤더** | `X-API-Key: <YOUR_API_TOKEN>` |

### 예시 요청 (cURL)

```bash
curl -X GET "https://api.procurize.com/v1/documents" \
  -H "X-API-Key: YOUR_API_TOKEN"
```

> 🧠 **조직 ID가 필요 없음** – 토큰이 조직에 바인딩되어 있어 API가 자동으로 컨텍스트를 결정합니다.

## 중요한 보안 및 사용 규칙

| 규칙 | 설명 |
|------|------|
| **토큰 권한** | 토큰은 생성자의 권한과 동일합니다. 사용자의 역할이 변경되면 토큰 권한도 자동 업데이트됩니다. |
| **조직 바인딩** | 토큰은 생성자의 조직에만 묶여 있습니다. 여러 조직에서 동일 토큰을 사용할 수 없습니다. |
| **토큰 가시성** | 토큰 값은 **한 번만** 표시됩니다. 즉시 저장하세요. Procurize.AI는 해시만 보관합니다. |
| **만료된 토큰** | 만료된 토큰은 자동으로 비활성화되며 사용할 수 없습니다. 필요 시 새 토큰을 생성하세요. |

## 문제 해결

| 문제 | 해결책 |
|------|--------|
| **"Invalid API key" 오류** | 토큰이 정확히 복사되었는지 확인하세요 (공백 없음). 토큰이 아직 활성 상태이며 만료되지 않았는지 확인합니다. |
| **역할 변경 후 토큰이 작동하지 않음** | 토큰 권한이 현재 사용자 역할에 맞게 업데이트됩니다. 사용자가 권한을 잃으면 토큰도 동일하게 작동하지 않습니다. |
| **토큰 분실** | 분실한 토큰을 폐기하고 새 토큰을 생성하세요. |
| **속도 제한** | 플랜에 따라 API 속도 제한이 적용됩니다. 응답 헤더의 `X-RateLimit-*` 값을 확인하세요. |

## 관련 주제

- [권한 개요](/what-user-permissions-does-procurize-have/) – 상세 역할 정의  
- [요금제]https://www.procurize.ai/pricing/ – 어떤 플랜에서 API 접근이 포함되는지  
- [REST API 레퍼런스](/rest-api-reference/) – 엔드포인트 상세 문서  

{{<article-feedback>}}