公開 API とアクセストークン

公開APIを使うと、自社のシステムやスクリプトからakamineの課題などを読み書きできます。この記事では、アクセストークンの発行と、使うときの決まりごとを説明します。

できること

• APIの入口は /api/v1 です。
• 認証は、アクセストークンだけです。ログインの画面を通りません。
• トークンの持ち主の権限を、そのまま使います。持ち主にできないことは、APIでもできません。
• ブラウザのための操作（同時編集の仕組みなど）は、公開されていません。

アクセストークンを発行する

有効なユーザーなら、誰でも自分のトークンを発行できます。

1. 個人設定の「API」を開きます。
2. パスワードの確認が出たら、パスワードを入れて「確認」を押します。
3. 名前、スコープ、有効期限を決めて、トークンを発行します。
4. 表示されたトークンの文字列を控えます。

項目	内容
名前	どこで使うトークンかわかる名前
スコープ	「読み取り」（取得だけ）か「読み取りと書き込み」
有効期限	期限なしも選べる

スコープは、持ち主の権限をさらに狭めるだけです。広げることはできません。トークンは1人25個までです。

トークンの発行と失効は、ブラウザでakamineにログインした状態でだけできます。トークンから、別のトークンは作れません。

使い方

要求のヘッダーに、トークンを付けます。トークンは aka_ で始まる文字列です。

Authorization: Bearer aka_...

• 一覧は ?page= と ?per_page=（最大100）で取得します。結果は data と meta に入ります。
• エラーは、message、code、errors を持つJSONで返ります。
• 作成（POST）のときに Idempotency-Key ヘッダー（255文字まで）を付けると、同じキーでの再送は、最初に成功した結果が返ります（24時間）。通信が途切れても、課題が二重にできません。
• 読み取りのトークンで書き込もうとすると、403が返ります。
• 1分間に300回を超えると、429が返ります。Retry-After ヘッダーの秒数だけ待ってから、再開してください。

リファレンス

個人設定の「API」の画面に、使い方の案内と、curlの例が載っています。機械で読める仕様書（OpenAPI 3）は、/api/v1/openapi.json にあります。

トークンが使えなくなるとき

次の場合、トークンは止まります。

• 持ち主が停止された。
• 失効した、または有効期限が切れた。
• システム全体で2段階認証が必須なのに、持ち主が設定していない。

持ち主の権限が変わったときは、その分だけトークンの権限も変わります。

失効する

持ち主は、個人設定の「API」から失効できます。システム管理者は、システム管理の「API」で、全員の有効なトークンを見て、心当たりのないものを失効できます。

関連する記事

• Webhookで外部へ送る
• 個人のAPI
• 役割と権限
• 受信メールから課題を作る