# 액세스 토큰 획득하기

API를 사용하기 위해서는 API를 사용할 계정에 연결된 **액세스 토큰**을 발급받아야 합니다.
이 문서에서는 액세스 토큰을 획득하는 방법을 설명한 후, 기본적인 API 사용법을 설명합니다.

기본적으로 API는 요청 시 액세스 토큰이 필요합니다.
액세스 토큰은 사용자에 연결된 인증 정보로, API를 이용하는 사용자를 식별하는 동시에 액세스 토큰별로 어떤 작업 권한을 가지고 있는지 관리합니다.

:::tip
사용자와 그 사용자와 연결된 액세스 토큰은 일대다 관계이며, 한 사용자에게 여러 개의 액세스 토큰이 발급될 수 있습니다.
:::

자신의 액세스 토큰을 쉽게 획득할 수 있을 뿐만 아니라, 자신의 애플리케이션을 사용하게 될 불특정 사용자의 액세스 토큰을 획득할 수도 있습니다.

- 전자의 경우: \*\*"자신의 액세스 토큰을 수동으로 발행하기"\*\*로 이동합니다.
- 후자의 경우: \*\*"애플리케이션 사용자에게 액세스 토큰 발급 요청하기"\*\*로 이동합니다.

### 자신의 액세스 토큰을 수동으로 발행하기

Misskey Web의 '설정 > API'에서 자신의 액세스 토큰을 발행할 수 있습니다.

:::danger
액세스 토큰은 다른 사람이 알 수 없도록 해야 합니다.
:::

### 애플리케이션 사용자에게 액세스 토큰 발급 요청하기

애플리케이션을 이용하는 사용자(이하 단순히 '사용자'라 칭함)의 액세스 토큰을 발급받으려면 아래 절차에 따라 발급을 요청합니다.

:::tip

아래 설명할 방법은 앱을 만들지 않고 즉시 액세스 토큰을 발급하는 MiAuth라는 방법입니다.

[앱 생성 방식으로 액세스 토큰을 획득하는 방법도 있습니다(구식).](./app)
:::

#### Step 1

UUID를 생성합니다.이후 이를 **세션 ID**라고 부릅니다.

:::danger
이 세션 ID는 매번 생성해야 하며, 반복해서 사용하지 않도록 해야 합니다.
:::

#### Step 2

애플리케이션 인증 양식을 사용자의 브라우저에 표시하도록 합니다.인증 양식은 다음 형식의 URL로 열 수 있습니다.

```
https://{host}/miauth/{session}
```

여기서,

- `{host}`부분은 사용자 서버의 호스트로 대체합니다.보통 호스트는 사용자가 입력합니다.
- `{session}`부분은 세션 ID로 대체합니다.

또한 URL에 몇 가지 옵션을 쿼리 파라미터로 설정할 수 있습니다.

| 이름           | 설명                                                                                       |
| ------------ | ---------------------------------------------------------------------------------------- |
| `name`       | 애플리케이션 이름。                                                                               |
| `icon`       | 애플리케이션 아이콘의 이미지 URL。                                                                     |
| `callback`   | 인증이 끝난 후 리디렉션되는 URL。<br> 리디렉션 시에는 `session`이라는 쿼리 파라미터로 세션 ID가 붙습니다.                     |
| `permission` | 애플리케이션이 요구하는 권한.<br> 요청하는 권한을 `,`로 구분하여 열거합니다.권한 목록은 [여기](./permission.md)에서 확인할 수 있습니다. |

:::tip{label='例'}

```
https://misskey.io/miauth/c1f6d42b-468b-4fd2-8274-e58abdedef6f?name=MyApp&callback=https%3A%2F%2Fmyapp.example.com%2Fcallback&permission=write:notes,write:following,read:drive
```

:::

#### Step 3

사용자가 애플리케이션 접근을 허용한 후 다음 형식의 URL에 POST 요청하면 응답으로 액세스 토큰이 포함된 JSON이 반환됩니다.

```
https://{host}/api/miauth/{session}/check
```

여기서,

- `{host}`부분은 사용자 서버의 호스트로 대체합니다.
- `{session}`부분은 세션 ID로 대체합니다.

응답에 포함된 속성은 다음과 같습니다.

| 이름      | 설명          |
| ------- | ----------- |
| `token` | 사용자 액세스 토큰. |
| `user`  | 사용자 정보.     |

## API 이용

액세스 토큰을 획득하면 각종 엔드포인트에 요청하여 API를 사용할 수 있습니다.

:::tip

- HTTP API는 모두 POST이며, 요청/응답 모두 JSON 형식입니다(drive/files/create 제외).
- 요청 헤더에 `Content-Type: application/json`을 지정합니다.
- 액세스 토큰은 `i`라는 파라미터 이름으로 요청 본문 JSON에 포함합니다.
- 기본 URL은 `https://{서버의 도메인}/api`입니다.

:::

액세스 토큰이 있는 바디의 예시 (meta의 경우):.

```json
{
    "i": "HogEFugA1341",
    "detail": false
}
```

<!--TODO:「APIリファレンス」をリンクに差し替え-->

API에 대한 자세한 내용은 API 레퍼런스를 참조하세요.

:::warning
Misskey는 REST를 채택하고 있지 않습니다.
:::

또한 Misskey는 HTTP API뿐만 아니라 스트리밍 API도 제공하고 있습니다.스트리밍 API에 대한 자세한 내용은 [이 문서](./streaming/index.md)를 참고하세요.