6.13. Iris

6.13.1. Spaces API: Iris Integration and User Filtering

The /api/spaces/ endpoint now supports filtering spaces by username to determine what spaces a user can access. This feature allows Hub Admins to query a user’s space access based on their group memberships and Iris permissions.

Additionally, spaces and their associated sites include iris information to indicate whether they are Versity S3 presented, and what level of access the user has on each site.

6.13.1.1. Iris state

  • enabled: true - The space (and its associated sites) is Versity S3 presented.

  • enabled: false - The space is not Versity S3 presented.

6.13.1.2. Permissions and Group-Based Access

Iris permissions are defined per space per site, and are granted to groups. User Permissions are derived from the groups the user belongs to.

The possible permissions are

  1. readonly (default) - A user is granted readonly access if they belong only to groups with readonly permission (or no groups at all). Readonly users can list spaces but cannot upload/download to buckets.

  2. readwrite - A user is granted readwrite access if any of their groups have readwrite permission for a space-site. Readwrite users can fully upload/download to buckets.

Note

If a user belongs to multiple groups with different permissions on the same space-site, the highest permission (readwrite) is applied.

Permissions are advisory — they do not enforce access within Hub, but provided information to Iris.

6.13.1.3. REST API

GET /api/spaces/?username=<target_username>

  • The authenticated user must have admin privileges.

  • If username is not provided, the API returns spaces for the authenticated user by default and does not include Iris permissions.

6.13.1.4. Example for Iris Response Payload Structure

When Iris is enabled:

"iris": {
    "enabled": true,
    "user_permission": "readwrite"
}

When Iris is not enabled, user_permission is omitted from the payload.

"iris": {
    "enabled": false
}

6.13.1.5. Example Response with Iris User Permissions.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "url": "http://10.201.2.195:8000/api/spaces/2/",
            "id": 2,
            "uuid": "67d887c4-50c6-40f1-95f5-f1c346b12494",
            "name": "space-67",
            "mountpoint": "/mmfs1/data/space-67",
            "sites": [
                {
                    "id": 2,
                    "name": "siteA",
                    "label": "siteA",
                    "pool": "sas1",
                    "usage": null,
                    "iris": {
                        "enabled": true,
                        "user_permission": "readwrite"
                    }
                },
            ],
            "created": "2025-06-17T11:05:41.815258Z",
            "size": 10737418240,
            "snapshot_schedule": {
                "id": 1,
                "frequency": "1 00:00:00",
                "time": "00:05:00",
                "duration": "7 00:00:00",
                "space": 2
            },
            "on_sites": {
                "siteA": {
                    "name": "space-67",
                    "size": 10737418240,
                    "present": true
                }
            },
            "immutable": false,
            "editable": true,
            "color": [191, 99, 64],
            "permission_mode": null,
            "relationships": {
                "shares": [],
                "policies": [],
                "schedules": []
            },
            "nested_shares": {
                "samba": [],
                "nfs": []
            },
            "is_ready": true
        }
    ]
}

6.13.1.6. Example Response When User Has No Accessible Spaces

{
    "count": 0,
    "next": null,
    "previous": null,
    "results": []
}

6.13.1.7. Summary

  1. Returns spaces for the authenticated user if username is not provided.

  2. Returns 200 OK with no spaces if the target user does not exist.

  3. Returns 200 OK with no spaces if the user exists but has no group memberships.

  4. Returns 200 OK with no spaces if user’s groups do not have view_space permission.

  5. Returns all spaces where user’s groups have view_space permission.

  6. Supports additional filtering by site_id when both username and site_id are provided.

  7. Returns all spaces if the username is omitted or username=.

6.13.2. Groups API: Iris Permissions

The /api/groups/ endpoint supports assigning and retrieving Iris permissions for spaces.

Permissions are defined per space per site, and groups cannot have duplicate permissions on the same space-site combination.

Permissions currently support two levels:

  • readonly (default)

  • readwrite

If a user is a member of multiple groups with different permissions on the same space-site, the highest level (readwrite) is applied.

6.13.2.1. Example: View Group with Iris Permissions

GET /api/groups/1/
{
  "id": 1,
  "name": "iris-admin",
  "users": [
    {
      "username": "bob"
    }
  ],
  "iris_permissions": [
    {
      "space": "Project1",
      "site": "london",
      "permission": "readwrite"
    },
    {
      "space": "Project1",
      "site": "paris",
      "permission": "readonly"
    }
  ]
}

6.13.2.2. Example: Create Group with Iris Permissions

POST /api/groups/
{
  "name": "london-admin",
  "iris_permissions": [
    {
      "space": "Project1",
      "site": "london",
      "permission": "readwrite"
    }
  ]
}

6.13.2.3. Example: Update Group Permissions

PATCH /api/groups/1/
{
  "iris_permissions": [
    {
      "space": "Project1",
      "site": "london",
      "permission": "readwrite"
    },
    {
      "space": "Project1",
      "site": "paris",
      "permission": "readonly"
    }
  ]
}