REST API

外部のアプリケーションからkickflowを操作するREST API

Table of contents

  1. エンドポイント
  2. 各APIの詳細
  3. 認証
    1. アクセストークンの種類
    2. Personal Access Tokenによる認証
    3. Service Account Tokenによる認証
    4. 認証失敗時
  4. Role-based Access Control (RBAC)
  5. ページネーション
  6. ソート
  7. 利用制限
  8. オリジン間リソース共有（CORS）
  9. タイムゾーン
  10. エラーレスポンス

エンドポイント

  • https://api.kickflow.com/v1/
    • Content-Type: application/jsonのみ許可します

各APIの詳細

各APIの仕様はこちらからご確認ください。

また、OpenAPI 3.0の定義ファイルはこちらからダウンロードできます。

認証

アクセストークンの種類

kickflowではアクセストークンによる認証を行います。 アクセストークンにはユーザー個人に紐づくPersonal Access Tokenと、テナント全体にアクセス可能なService Account Tokenの二種類のアクセストークンがあります。

Personal Access Tokenはトークンを発行したユーザーの操作を自動化するのに使用します。一方、Service Account Tokenはテナント内の任意のユーザーになりすまして自動的に何らかの操作を実行するのに使用します。

Service Account Tokenは万が一漏洩した際に影響が大きいため、どうしても必要でない限りはPersonal Access Tokenの使用を検討してください。

Personal Access Tokenによる認証

アクセストークン設定画面から発行したPersonal Access Tokenを、下記の形式で Authorizationヘッダに設定してください。

Authorization: Bearer <アクセストークン>

Service Account Tokenによる認証

Personal Access Tokenと同様、AuthorizationヘッダにService Account Tokenを設定します。 さらに、なりすましたいユーザーのID（UUID）をX-Caller-Idヘッダに設定します。

Authorization: Bearer <アクセストークン>
X-Caller-Id: <ユーザーのUUID>

認証失敗時

認証に失敗した場合、kickflow REST APIは401 Unauthorizedを返却します。

Role-based Access Control (RBAC)

kickflowではユーザーの管理権限をRBACで管理しています。 アクセストークンに紐づくアクセス権限は、RBACによってユーザー（Service Account Tokenによる認証の場合はなりすまし先のユーザー）が持つ権限に一致します。 ユーザーが権限を持たないAPIを実行した場合、kickflowは403 Forbiddenを返却します。

ページネーション

一部のAPIではページネーションが可能です。 ページネーションが可能なAPIでは、pageとperPageをクエリパラメータに追加することで、指定したページのデータを取得することができます。

  • pageは何ページ目かを表します。1が最初のページです（0ではないことに注意してください）。設定しない場合、page=1とみなします。
  • perPageは1ページあたり何件のレコードを返すかを表します。デフォルト値は25で、最大100まで設定可能です。

レスポンスには RFC-8288 によるLinkヘッダーが付加されます。 さらに、現在のページ、1ページあたりの件数、合計件数もヘッダーに含まれます。

Link: <https://api.kickflow.com/v1/users?page=2&perPage=100>; rel="next",
  <https://api.kickflow.com/v1/users?page=50&perPage=100>; rel="last"
Page: 1
Per-Page: 100
Total: 4950

ソート

一部のAPIではソートが可能です。 ソートが可能なAPIでは、クエリパラメータにsortBy=[フィールド名]-[asc|desc]を付けることで、ソート対象のフィールドと昇順・降順を指定できます。

例えば、ユーザー一覧を取得するAPIの場合以下のようになります。

# メールアドレスで昇順
/v1/users?sortBy=email-asc

# メールアドレスで降順
/v1/users?sortBy=email-desc

APIによってソート可能なフィールドは限定されています。選択不可能なフィールドをクエリで指定した場合、そのクエリは無視されます。

利用制限

リクエスト元のIPアドレスごとに毎分30回までREST APIを実行可能です。これを超えた場合、kickflowはレスポンスとして429 Too Many Requestsを返します。

ユーザーが利用制限を回避できるようにするため、kickflowはレスポンスに下記のヘッダーを付加します。

ヘッダー 説明
RateLimit-Limit 単位時間あたりの実行回数上限
RateLimit-Remaining 現在のウィンドウ内での残り実行可能回数
RateLimit-Reset ウィンドウが次にリセットされる日時（UNIX時間）

大量にREST APIを実行す必要がある開発者向けに、有償にてREST APIの利用制限の上限値を緩和する「REST API利用枠オプション」も提供しています。 以下のようなヘッダをリクエストに追加することで、1分あたりの実行回数上限が300回まで増加します。

X-Rate-Limit-Secret: <有償オプション契約時に発行されたシークレット>

注意: 利用制限のしきい値は将来予告なく変更になる可能性があります。

オリジン間リソース共有（CORS）

kickflow REST APIはCORSをサポートしています。すべてのAPIはブラウザ上のJavaScriptから呼び出すことが可能です。

タイムゾーン

すべての日時のタイムゾーンはJSTです。日時のフォーマットはISO 8601に準拠します。

# 日時の例
2020-05-01T12:34:56.789+09:00

エラーレスポンス

エラー発生時、下記のような形式のJSONをレスポンスボディとして返却します。ただし、メンテナンス中や予期しない理由でエラーが発生した場合には、異なるレスポンスを返す可能性があります。

{
  "code": "validation_failed",
  "message": "hoge must not be empty",
  "errors": {
    "hoge": [
      "must not be empty"
    ]
  }
}

JSONには下記のフィールドが含まれます。

フィールド 必須 説明
code o エラーコード
message o エラーメッセージ
errors   フィールドごとのエラーのJSONオブジェクト（バリデーションエラー発生時のみ）
doc_url   参照ドキュメントのURL（一部のエラーのみ）

主なHTTPステータスとエラーコードは以下の通りです。これ以外のエラーコードを返す場合もあるほか、予告なくHTTPステータスコードやエラーコードは変更になる可能性があります。

HTTPステータスコード エラーコード 説明
400 invalid_parameter パラメータが不正（必須パラメータが不足、型が不正など）
400 invalid_content_type Content-Typeが不正
400 invalid_json JSONのパースに失敗
400 payload_too_large ペイロードやファイルのサイズが上限を超えている
400 invalid_header リクエストヘッダが不正
401 invalid_access_token アクセストークンが不正
401 user_not_registered ユーザーが招待されていない
401 user_inactive ユーザーが有効状態ではない
401 email_not_verified ユーザーのメールアドレスが認証されていない
401 invalid_caller_id サービスアカウントトークンによる認証時に、Caller IDが指定されていない
401 invitation_expired 招待の有効期限切れ
403 missing_permission 管理権限が不足
403 license_purchase_required 追加のライセンス購入が必要
403 upgrade_required アップグレードが必要
403 option_purchase_required オプション機能の購入が必要
403 invisible_ticket チケットが閲覧できない
403 user_not_assigned ユーザーがチケットに承認者としてアサインされていない
403 ticket_create_restricted チケットの作成が制限されている
403 ip_address_denied IPアドレス制限により拒否された
403 admin_is_working 管理者が作業中モード
403 tenant_suspended テナントが一時停止されている
403 resource_not_editable 編集ができないリソース（スーパー管理者、ルートフォルダなど）
404 resource_not_found 指定したリソースが存在しない
404 endpoint_not_found 指定したエンドポイントが存在しない
422 validation_failed リクエスト形式は正しいが、ビジネスロジックのバリデーションに通らなかった
422 invalid_state リクエスト形式は正しいが、リソースの状態が原因で失敗した
422 domain_not_allowed ユーザーのメールアドレスが許可されていないドメイン
422 assignment_required_before_approve チケット承認前に、次の承認者の指名が必要
422 input_required_before_approve チケット承認前に、フォームの入力が必要
429 rate_limited 短期間で大量にリクエストしたため、利用制限がかかっている
500 internal_server_error サーバー内部のエラー
503 feature_disabled 一時的に機能が利用不可

Copyright © 2025 kickflow, Inc.