jointrashposs/content/ko/docs/4.for-developers/api/token.md

액세스 토큰 획득하기

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

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

:::tip

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

:::

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

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

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

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

:::danger

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

:::

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

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

:::tip

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

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

:::

Step 1

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

:::danger

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

:::

Step 2

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

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

여기서,

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

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

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

:::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의 경우):.

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

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

:::warning

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

:::

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