5.1 KiB
액세스 토큰 획득하기
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에 대한 자세한 내용은 이 문서를 참고하세요.