Get All Roles

curl --request GET \
  --url https://secureai.hiperai.ai/api/external/roles \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://secureai.hiperai.ai/api/external/roles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "roles": [
    {
      "id": "60a7c8f5e8b4f5001f7a8c26",
      "name": "custom_role",
      "displayName": "Custom Role",
      "description": "Custom role with specific permissions",
      "isSystem": false,
      "hasAdminPanelAccess": true,
      "permissions": [
        {
          "section": "user-management",
          "level": "admin"
        }
      ],
      "canInteractWithAI": true,
      "canUseChat": true,
      "userCount": 5,
      "createdBy": {
        "id": "60a7c8f5e8b4f5001f7a8c24",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

GET

roles

Get All Roles

curl --request GET \
  --url https://secureai.hiperai.ai/api/external/roles \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://secureai.hiperai.ai/api/external/roles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "roles": [
    {
      "id": "60a7c8f5e8b4f5001f7a8c26",
      "name": "custom_role",
      "displayName": "Custom Role",
      "description": "Custom role with specific permissions",
      "isSystem": false,
      "hasAdminPanelAccess": true,
      "permissions": [
        {
          "section": "user-management",
          "level": "admin"
        }
      ],
      "canInteractWithAI": true,
      "canUseChat": true,
      "userCount": 5,
      "createdBy": {
        "id": "60a7c8f5e8b4f5001f7a8c24",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

{
  "success": false,
  "error": "Invalid API key",
  "message": "The provided API key is invalid or has been revoked",
  "request_id": "req-abc123"
}

役割をリストする

SecureAI システムで利用可能なすべてのユーザーロールを取得します。

エンドポイント

GET /roles

説明

このエンドポイントは、SecureAI システムで利用可能なすべてのユーザーロールを返します。権限、説明、メタデータなど、各ロールに関する詳細情報が提供されます。これは、利用可能な役割とその機能を理解するのに役立ちます。

認証

必須: 管理者権限を持つ API キー

Authorization: Bearer sk-your-api-key-here

クエリパラメータ

パラメータ	タイプ	必須	説明
`page`	整数	いいえ	1	ページネーションのページ番号 (デフォルト: 1)
`limit`	整数	いいえ	20	ページごとのロールの数 (デフォルト: 20)
`search`	文字列	いいえ	-	名前、表示名、または説明の検索語
`isSystem`	文字列	いいえ	-	システムの役割によるフィルター (true/false)
`sortBy`	文字列	いいえ	作成場所	並べ替えの基準となるフィールド (デフォルト: “createdAt”)
`sortOrder`	文字列	いいえ	説明	ソート順序 (asc/desc、デフォルト: “desc”)

リクエストの例

GET /roles?page=1&limit=10&search=admin

成功の応答

ステータスコード: 200 OK

{
  "success": true,
  "roles": [
    {
      "id": "60a7c8f5e8b4f5001f7a8c26",
      "name": "custom_role",
      "displayName": "Custom Role",
      "description": "Custom role with specific permissions",
      "isSystem": false,
      "hasAdminPanelAccess": true,
      "permissions": [
        {
          "section": "user-management",
          "level": "admin"
        },
        {
          "section": "index-management",
          "level": "reader"
        }
      ],
      "canInteractWithAI": true,
      "canUseChat": true,
      "userCount": 5,
      "createdBy": {
        "id": "60a7c8f5e8b4f5001f7a8c24",
        "name": "John Doe",
        "email": "john@example.com"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

応答フィールド

フィールド	タイプ	説明
`success`	ブール値	操作が成功したかどうかを示します。
`roles`	配列	ロールオブジェクトの配列
`roles[].id`	文字列	一意のロール識別子
`roles[].name`	文字列	役割名
`roles[].displayName`	文字列	ロールの表示名
`roles[].description`	文字列	役割の説明
`roles[].isSystem`	ブール値	これがシステムの役割であるかどうか
`roles[].hasAdminPanelAccess`	ブール値	ロールに管理パネルへのアクセス権があるかどうか
`roles[].permissions`	配列	権限オブジェクトの配列
`roles[].permissions[].section`	文字列	許可セクション
`roles[].permissions[].level`	文字列	許可レベル
`roles[].canInteractWithAI`	ブール値	ロールが AI と対話できるかどうか
`roles[].canUseChat`	ブール値	ロールがチャットを使用できるかどうか
`roles[].userCount`	整数	このロールを持つユーザーの数
`roles[].createdBy`	オブジェクト	ロールを作成したユーザー
`roles[].createdBy.id`	文字列	作成者ユーザーID
`roles[].createdBy.name`	文字列	作成者名
`roles[].createdBy.email`	文字列	作成者のメールアドレス
`roles[].createdAt`	文字列	作成タイムスタンプ
`roles[].updatedAt`	文字列	最終更新タイムスタンプ
`pagination`	オブジェクト	ページネーション情報
`pagination.page`	整数	現在のページ番号
`pagination.limit`	整数	ページごとの項目
`pagination.total`	整数	ロールの総数
`pagination.pages`	整数	総ページ数

使用例

JavaScript

const listRoles = async (params = {}) => {
  const queryString = new URLSearchParams(params).toString();
  const url = `https://{customer.name}.hiperai.ai/api/external/roles${queryString ? `?${queryString}` : ''}`;
  
  const response = await fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer sk-your-api-key-here'
    }
  });
  
  return await response.json();
};

// Example usage
const result = await listRoles({
  page: 1,
  limit: 10,
  search: 'admin'
});
console.log(result.roles);

パイソン

import requests

def list_roles(params=None):
    url = "https://{customer.name}.hiperai.ai/api/external/roles"
    headers = {
        "Authorization": "Bearer sk-your-api-key-here"
    }
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Example usage
params = {
    "page": 1,
    "limit": 10,
    "search": "admin"
}

result = list_roles(params)
print(result["roles"])

cURL

curl -X GET "https://{customer.name}.hiperai.ai/api/external/roles?page=1&limit=10&search=admin" \
  -H "Authorization: Bearer sk-your-api-key-here"

エラー応答

401 不正

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 禁止

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Admin privileges required"
  }
}

429 リクエストが多すぎます

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "retryAfter": 60
  }
}

使用例

ロール管理: ユーザー割り当てに使用可能なすべてのロールをリストします。
権限の確認: 各役割にどのような権限があるかを理解します。
アクセス制御: 利用可能な役割に基づいてユーザーアクセスを計画します。
ユーザー割り当て: ニーズに基づいてユーザーに役割を割り当てます。
ロール分析: ロールの使用状況とユーザー分布を分析します。

レート制限

デフォルト: 1 分あたり 100 リクエスト
毎日: 1 日あたり 10,000 リクエスト
毎月: 毎月 300,000 件のリクエスト

注意事項

このエンドポイントには管理者権限が必要です
ページベースのページネーション: オフセットではなくページパラメータを使用します。
検索: 名前、表示名、および説明フィールドを検索します。
システムロール: システムロールとカスタムロールでフィルタリングできます。
並べ替え: 任意のフィールドで昇順または降順に並べ替えることができます
フラットな応答: 応答はデータオブジェクトの下にネストされていません
ユーザー数: 各ロールを持つユーザーの数を示します。
作成者情報: 各ロールの作成者を表示します。

承認

Authorization

string

header

必須

API key authentication using Bearer token format. Example: Authorization: Bearer sk-your-api-key-here

クエリパラメータ

page

integer

デフォルト:1

Page number for pagination

必須範囲: x >= 1

limit

integer

デフォルト:20

Number of roles per page

必須範囲: 1 <= x <= 100

string

Search term for role name, display name, or description

isSystem

enum<string>

Filter by system roles

利用可能なオプション:

true,

false

sortBy

string

デフォルト:createdAt

Field to sort by

sortOrder

enum<string>

デフォルト:desc

Sort order

利用可能なオプション:

asc,

desc

レスポンス

List of roles

success

boolean

例:

true

roles

object[]

Show child attributes

pagination

object

Show child attributes

導入 & セットアップ

モデル & AI 生成

ナレッジベース & RAG

セキュリティ、ガードレール & 監査

ユーザー & アクセス (IAM)

請求、クォータ & Webhook

役割のリスト

役割をリストする

エンドポイント

説明

認証

クエリパラメータ

リクエストの例

成功の応答

応答フィールド

使用例

JavaScript

パイソン

cURL

エラー応答

401 不正

403 禁止

429 リクエストが多すぎます

使用例

レート制限

注意事項

承認

クエリパラメータ

レスポンス

​役割をリストする

​エンドポイント

​説明

​認証

​クエリパラメータ

​リクエストの例

​成功の応答

​応答フィールド

​使用例

​JavaScript

​パイソン

​cURL

​エラー応答

​401 不正

​403 禁止

​429 リクエストが多すぎます

​使用例

​レート制限

​注意事項

承認

クエリパラメータ

レスポンス

役割をリストする

エンドポイント

説明

認証

クエリパラメータ

リクエストの例

成功の応答

応答フィールド

使用例

JavaScript

パイソン

cURL

エラー応答

401 不正

403 禁止

429 リクエストが多すぎます

使用例

レート制限

注意事項