> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# auth_status

> 현재 인증 상태와 권한 확인

## 개요

`auth_status`는 인증 방식, 사용자 신원, 부여된 scope 등 현재 인증 상태에 관한 정보를 반환해요. 이 도구는 파라미터도, 특정 scope도 필요하지 않아요.

**주요 사용 사례:**

* 인증이 올바르게 구성됐는지 확인
* 다른 도구가 권한 오류를 반환할 때 권한 문제 디버깅
* 도구를 호출하기 전에 어떤 scope가 사용 가능한지 확인

**핵심 기능:**

* 파라미터 불필요
* scope 불필요
* 완전한 인증 컨텍스트 반환

***

## 파라미터

이 도구는 파라미터를 받지 않아요.

### 요청 예시

```json theme={"system"}
{}
```

***

## 응답 형식

### 성공 응답

```json theme={"system"}
{
  "authenticated": true,
  "authMethod": "api_key",
  "userId": 12345,
  "workspaceGuid": null,
  "clientId": "client_001",
  "scopes": [
    "mcp:notes:read",
    "mcp:folders:read"
  ]
}
```

**필드 설명:**

| Field           | Type           | Description                             |
| --------------- | -------------- | --------------------------------------- |
| `authenticated` | boolean        | 이 도구가 성공적으로 반환되면 항상 `true`              |
| `authMethod`    | string         | 사용된 인증 방식: `jwt` 또는 `api_key`           |
| `userId`        | number \| null | 인증된 사용자의 ID (user 범위 key일 때 존재)         |
| `workspaceGuid` | string \| null | workspace GUID (workspace 범위 key일 때 존재) |
| `clientId`      | string         | 클라이언트 애플리케이션 ID                         |
| `scopes`        | string\[]      | 부여된 권한 scope 목록                         |

***

## scope 이해하기

`scopes` 배열은 사용자가 어떤 도구를 사용할 권한이 있는지 나타내요:

| Scope              | Grants Access To                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `mcp:notes:read`   | `list_notes`, `search_notes`, `get_note`, `get_note_transcript`, `list_document_templates`, `get_document_template`, `get_share_link` |
| `mcp:folders:read` | `search_private_folders`, `search_team_folders`                                                                                       |

***

## 사용 예시

### 권한 오류 디버깅

도구 호출이 `403 Forbidden` 오류를 반환하면 `auth_status`로 scope를 확인하세요:

```json theme={"system"}
// 1. Call auth_status
{}

// 2. Check the response
{
  "authenticated": true,
  "authMethod": "api_key",
  "userId": 12345,
  "workspaceGuid": null,
  "clientId": "client_001",
  "scopes": ["mcp:notes:read"]
}
```

이 예시에서 key는 `mcp:notes:read` scope만 가지고 있어요. 다른 scope가 필요한 도구(예: 폴더 검색에 필요한 `mcp:folders:read`)는 `403 Forbidden`을 반환해요.

### API key 종류 확인

user 범위 key를 쓰는지 workspace 범위 key를 쓰는지 판단하려면 `userId`와 `workspaceGuid`를 확인하세요:

* **user 범위 key:** `userId`에 사용자 식별자가 들어 있음 (여러 workspace에 걸칠 수 있음)
* **workspace 범위 key:** `workspaceGuid`에 workspace 식별자가 들어 있고, 단일 workspace에 묶여 있음

***

## 자주 발생하는 오류

### 유효하지 않거나 만료된 자격 증명

<Error>
  ```json theme={"system"}
  {
    "error": "Authentication failed. Invalid or expired credentials.",
    "code": "UNAUTHORIZED",
    "statusCode": 401
  }
  ```
</Error>

**해결 방법:** API key 또는 JWT token이 올바르고 만료되지 않았는지 확인하세요. 필요하면 새 key를 발급하세요.

***

## 권장 사례

<AccordionGroup>
  <Accordion title="시작 시 auth_status 호출하기">
    MCP 클라이언트를 초기화할 때 `auth_status`를 먼저 호출해서 연결 상태를 확인하고 사용 가능한 scope를 점검하세요. 다른 도구를 호출하기 전에 구성 문제를 조기에 잡아낼 수 있어요.
  </Accordion>

  <Accordion title="문제 해결에 활용하기">
    도구가 예상치 못한 권한 오류를 반환하면 `auth_status`가 문제를 진단하는 가장 빠른 방법이에요. 필요한 scope가 `scopes` 배열에 있는지, 올바른 API key 유형을 쓰고 있는지 확인하세요.
  </Accordion>
</AccordionGroup>