Multi-graph management

Permission types

Authorization scope

• GLOBAL: Global grant and revoke. When a user is granted a global permission, the user has the corresponding operation permission on all data objects in the entire graph engine. For example, the global READ permission lets the user query any subgraph.

• Subgraph scope (database): Grant and revoke at the database granularity. When a user is granted access to a subgraph (database), the user has the corresponding operation permission on all data objects inside that subgraph.

Create a subgraph

• Request URL: POST /db/add

• Description: creates a new subgraph.

• Required permission: can be called only by a global ADMIN account.

• Sample request:

  curl -X POST 'http://{host}:{port}/db/add' \
    -H 'Content-Type: application/json' \
    -u 'root_user:root_password' \
    -d '{
      "db": "my_graph",
      "params": {}
    }'
  

• Parameters:

  Field	Type	Required	Description
  db	String	Yes	The subgraph name. Only lowercase letters (a-z), digits (0-9), and underscores (_) are allowed. Note: user cannot be used as the name.
  params	JSON	No	Additional configuration parameters for the subgraph, provided as a JSON object.

• Sample response:

  {
    "status": "200 OK",
    "payload": {
      "result": true
    }
  }
  

List subgraphs

• Request URL: GET /db/list or GET /db/list?db={dbName}

• Description: lists one or all subgraphs.

• Required permission: any authenticated user can call this API.

• Sample request:

  # List all subgraphs
  curl -X GET 'http://{host}:{port}/db/list' \
    -u 'root_user:root_password'
  
  # List a specific subgraph
  curl -X GET 'http://{host}:{port}/db/list?db=my_graph' \
    -u 'root_user:root_password'
  

• Parameters:

  Parameter	Type	Required	Description
  db	String	No	The name of the subgraph to query. If left empty, all subgraphs in the current instance are returned.

• Sample response:

  {
    "status": "200 OK",
    "payload": [
      {
        "creationTime": 1670813317324,
        "dbName": "my_graph",
        "lastModified": 1670813317324,
        "params": "{}"
      },
      {
        "creationTime": 1670813326798,
        "dbName": "my_graph_02",
        "lastModified": 1670813326798,
        "params": "{}"
      }
    ]
  }
  

Delete a subgraph

• Request URL: GET /db/del

• Description: deletes the specified subgraph and all data it contains.

• Required permission: can be called only by a global ADMIN account.

• Sample request:

  curl -X GET 'http://{host}:{port}/db/del?db=my_graph' \
    -u 'root_user:root_password'
  

  Note

  If db is passed as default, the operation clears the database, but default still exists. If another schema is passed, the entire db is deleted.

• Parameters:

  Parameter	Type	Required	Description
  db	String	Yes	The name of the subgraph to delete.

• Sample response:

  {
    "status": "200 OK",
    "payload": {
      "result": true
    }
  }
  

Add a user

• Request URL: GET /user/add?user={name}&password={pwd}

• Description: creates a user for accessing subgraphs. Functionally equivalent to creating a user on the User Management page of the console.

• Required permission: can be called only by a global ADMIN user.

• Sample request:

  curl -X GET 'http://{host}:{port}/user/add?user=sub_user_01&password=sub_pwd_01' \
    -u 'root_user:root_password'
  

• Parameters:

  Parameter	Type	Required	Description
  user	String	Yes	The name of the new user.
  password	String	Yes	The login password of the user.

• Sample response:

  {
    "status": "200 OK",
    "payload": {
      "result": true
    }
  }
  

List users

• Request URL: GET /user/list or GET /user/list?user={name}

• Description: queries the information and role assignments of one or all users.

• Required permission: can be called only by a global ADMIN user.

• Sample request:

  # List all users
  curl -X GET 'http://{host}:{port}/user/list' \
    -u 'root_user:root_password'
  
  # List a specific user
  curl -X GET 'http://{host}:{port}/user/list?user=sub_user_01' \
    -u 'root_user:root_password'
  

• Parameters:

  Parameter	Type	Required	Description
  user	String	No	The name of the user to query. If left empty, all users are returned.

• Sample response:

  Note

  The * below stands for global.

  {
    "payload": [
      {
        "roles": {
          "test1": "WRITER",
          "test2": "WRITER",
          "test4": "WRITER"
        },
        "user": "test_user"
      },
      {
        "roles": {
          "*": "ADMIN"
        },
        "user": "root"
      },
      {
        "roles": {
          "*": "ADMIN"
        },
        "user": "test_user_admin"
      }
    ],
    "status": "200 OK"
  }

Grant a role

• Request URL: GET /role/grant?db={dbName}&user={name}&role={role}

• Description: grants a specified user the role permissions to access a specific subgraph.

• Required permission: a global ADMIN user.

• Sample request:

  curl -X GET 'http://{host}:{port}/role/grant?db=my_graph&user=sub_user_01&role=WRITER' \
    -u 'root_user:root_password'
  

• Parameters:

  Parameter	Type	Required	Description
  db	String	Yes	The name of the target subgraph. Use * to grant GLOBAL permission.
  user	String	Yes	The name of the target user.
  role	String	Yes	The role name to grant. Must be uppercase. READER: Read-only permission. The user can perform read operations only on the granted subgraphs. WRITER: Read/write permission. Includes all READER permissions plus write permission. ADMIN: When an account is granted global ADMIN, it can create subgraphs, create accounts, purge subgraphs, and so on. (In the User Management module of the console, READ, WRITE, and ADMIN must be granted together.)

• Sample response:

  {
    "status": "200 OK",
    "payload": {
      "result": true
    }
  }
  

Revoke a role

• Request URL: GET /role/revoke?db={dbName}&user={name}

• Description: revokes all permissions of a specified user on a specific subgraph.

• Required permission: global ADMIN user.

• Sample request:

  curl -X GET 'http://{host}:{port}/role/revoke?db=my_graph&user=sub_user_01' \
    -u 'root_user:root_password'
  

  Note

  You cannot revoke your own ADMIN role.

• Parameters:

  Parameter	Type	Required	Description
  db	String	Yes	The name of the target subgraph.
  user	String	Yes	The name of the target user.

• Sample response:

  {
    "status": "200 OK",
    "payload": {
      "result": true
    }
  }
  

List all role assignments

• Request URL: GET /role/all

• Description: lists all user-subgraph-role assignments in the current instance, for permission audit purposes.

• Required permission: global ADMIN user.

• Sample request:

  curl -X GET 'http://{host}:{port}/role/all' \
    -u 'root_user:root_password'
  

• Sample response:

  {
    "payload": [
      {
        "dbName": "test1",
        "role": "WRITER",
        "user": "test_user"
      },
      {
        "dbName": "test2",
        "role": "WRITER",
        "user": "test_user"
      },
      {
        "dbName": "test3",
        "role": "WRITER",
        "user": "test_user"
      },
      {
        "dbName": "*",
        "role": "ADMIN",
        "user": "test_user_admin"
      },
      {
        "dbName": "*",
        "role": "ADMIN",
        "user": "root"
      }
    ],
    "status": "200 OK"
  }