액세스 토큰 획득하기

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

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

도움말

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

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

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

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

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

경고

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

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

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

도움말

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

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

Step 1

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

경고

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

Step 2

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

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

여기서,

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

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

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

例

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를 사용할 수 있습니다.

도움말

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

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

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

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

주의

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

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