Contents

認証と認可

Cacoo API への認証方式は以下の３つがあります。

1. API キー

リクエストにユーザーごとに発行された API キーを付加して認証する方式です。 API キーはログイン後にここから発行できます。

リソースへのアクセス時に、発行された API キーをリクエストヘッダー X-Api-Key またはクエリパラメーター apiKey として付加することで認証が行えます。 URL に含まれた API キーはアクセスログ、ブラウザーの履歴、Referer ヘッダーに残る可能性があるため、リクエストヘッダーでの送信をおすすめします。

例（リクエストヘッダー）

API キーはリクエストヘッダー X-Api-Key で送信します。

curl -H "X-Api-Key: abcdefghijklmn" https://cacoo.com/api/v1/diagrams.json

例（クエリパラメーター）

API キーはクエリパラメーター apiKey で送信することもできます。既存の連携が動き続けるよう引き続き利用できますが、おすすめしません。 リクエストヘッダーとクエリパラメーターの両方が指定された場合は、クエリパラメーターが使われます。

https://cacoo.com/api/v1/diagrams.json?apiKey=abcdefghijklmn

2. OAuth 1.0a

OAuth 1.0a による認証方式です。アプリケーションの登録はログイン後にここから行います。

以下の URL で Access Token の取得を行います。

Access Token:

https://cacoo.com/oauth/access_token

Authorize:

https://cacoo.com/oauth/authorize

Request Token:

https://cacoo.com/oauth/request_token

OAuth での認証からアカウント登録を行う場合、以下のパラメータを Authorize の URL に指定することで、アカウント登録フォームへの事前入力ができます。

NameDescription
signup.mailAddressアカウントのメールアドレス
signup.nicknameアカウントのニックネーム

3. OAuth 2.0

OAuth 2.0（認可コードフロー）による認証方式です。アプリケーションの登録はログイン後にここから行います。動的クライアント登録（RFC 7591）には対応していないので、MCP クライアントなどからも、事前に登録したアプリケーションの client_id を使ってください。

エンドポイント

用途URL
認可https://cacoo.com/oauth2/authorize
トークンhttps://cacoo.com/oauth2/token
トークンの取り消しhttps://cacoo.com/oauth2/revoke
認可サーバーのメタデータhttps://cacoo.com/.well-known/oauth-authorization-server

アプリケーションの種別

種別用途client_secretPKCE
クライアントclient_secret を安全に保管できるアプリケーション（サーバーなど）トークンの取得・更新・取り消しで必要推奨
ブラウザclient_secret を保管できないアプリケーション（ブラウザ、スマートフォン、デスクトップ、AI エージェントなど）使いません必須

登録画面の「コンシューマーキー」が client_id、「コンシューマーシークレット」が client_secret です。クライアント種別では、client_id と client_secret を HTTP Basic 認証（client_secret_basic）か、リクエストボディ（client_secret_post）のどちらか一方で送ります。

コールバック URL はあらかじめ登録が必要です。認可リクエストの redirect_uri は、登録した URL と完全に一致（ポート番号を含む）しなければなりません。ポート番号が変わるループバックアドレス（RFC 8252）には対応していないので、ローカルで受け取る場合も固定のポートを登録してください。

手順 1. 認可リクエスト

ユーザーのブラウザを認可の URL に移動させます。ユーザーが同意すると、コールバック URL に code と state が付いて戻ります。

パラメータ必須説明
response_type○code
client_id○コンシューマーキー
redirect_uri登録したコールバック URL のいずれか。登録が 1 つなら省略できます
scope許可を求める権限。半角スペース区切り（後述）
stateCSRF 対策の値。コールバックにそのまま返ります
code_challengePKCE のチャレンジ（43〜128 文字）。ブラウザ種別では必須
code_challenge_methodS256（推奨）または plain。省略すると plain

ユーザーが拒否した場合や、パラメータに誤りがある場合は、コールバック URL に error（access_denied、invalid_scope、invalid_request など）と state が付いて戻ります。client_id やコールバック URL が正しくない場合は、コールバック URL に戻らず 400 になります。

手順 2. トークンの取得

code を受け取ったら、10 分以内にトークンのエンドポイントに POST します（application/x-www-form-urlencoded）。code は 1 回しか使えません。

パラメータ必須説明
grant_type○authorization_code
code○受け取った code
redirect_uri○認可で使われたコールバック URL（省略した場合は登録済みのコールバック URL）
client_id○コンシューマーキー（HTTP Basic 認証で送る場合は不要）
client_secretコンシューマーシークレット。クライアント種別で、HTTP Basic 認証を使わない場合は必須
code_verifierPKCE の検証値。認可で code_challenge を送った場合は必須
{
  "access_token": "...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "api"
}

アクセストークンの有効期限は 1 時間です。リフレッシュトークンは発行から 30 日有効で、更新のたびに新しいものが発行されるので、30 日以内に更新すれば使い続けられます。scope は許可されたスコープで、スコープを付けずに認可した場合は api です。

手順 3. API の呼び出し

アクセストークンを Authorization ヘッダーで送ります。401 が返った場合は、トークンを更新してから再送してください。

Authorization: Bearer <access_token>

手順 4. トークンの更新

アクセストークンの期限が切れたら、リフレッシュトークンで新しいトークンを取得します。

パラメータ必須説明
grant_type○refresh_token
refresh_token○リフレッシュトークン
client_id○コンシューマーキー（HTTP Basic 認証で送る場合は不要）
client_secretコンシューマーシークレット。クライアント種別で、HTTP Basic 認証を使わない場合は必須
scope許可された範囲より狭い権限のアクセストークンが必要な場合に指定します

レスポンスは「トークンの取得」と同じ形式です。新しいリフレッシュトークンが返り、使ったリフレッシュトークンは使えなくなります。 次回の更新には新しいリフレッシュトークンを使ってください。

手順 5. トークンの取り消し

連携を解除するときは、取り消しのエンドポイントに POST します（RFC 7009）。

パラメータ必須説明
token○取り消すトークン
token_type_hintrefresh_token または access_token
client_id○コンシューマーキー（HTTP Basic 認証で送る場合は不要）
client_secretコンシューマーシークレット。クライアント種別で、HTTP Basic 認証を使わない場合は必須

リフレッシュトークンを取り消すと、そのユーザーがこのアプリケーションに許可したすべてのトークンが無効になります。アクセストークンを取り消した場合は、そのトークンだけが無効になります。存在しないトークンを指定しても 200 を返します。

スコープ

スコープは、今後公開する API v2 で使います。現在の API v1 で使えるのは、スコープを付けずに認可したトークンだけです。

スコープ許可される操作
diagram:read図、コメント、チャットメッセージの閲覧とエクスポート。図を探すためのフォルダと組織の閲覧
diagram:write図の作成、編集、コピー、移動
diagram:archive図のアーカイブとその解除（アーカイブすると公開リンクが無効になり、組織の図は共同編集者も外れ、90 日後に削除されます）
diagram:delete図の削除（元に戻せません）
comment:writeユーザーの名前でのコメント投稿
  • アクセス種別が「読み込みのみ」のアプリケーションには、diagram:read だけが許可されます。diagram:read 以外だけを求めた場合は invalid_scope で戻ります。
  • スコープを付けずに認可したトークンは API v1 専用で、API v2 では使えません。
  • スコープを付けたトークンは API v1 では使えません。

エラー

トークンと取り消しのエンドポイントは、エラー時に RFC 6749 の形式の JSON を返します。

{
  "error": "invalid_grant",
  "error_description": "..."
}