Skip to main content
Skip table of contents

Fetching Groups via the API

Groups provide a means to organise multiple accounts collectively. The OpenAthens user administration interface allows operations to be performed on groups of accounts. Currently, the API provides only limited support for groups.

Fetching a group

The group(s) an individual account is a member of is returned as part of the application/vnd.eduserv.iam.account-v1+json object. Further information about a group can be obtained by fetching a group object.

Prerequisites

To fetch group information, a client application must

  • authenticate to the API as described in Authenticating to the API.
  • obtain an account object, or a list of groups for an organisation.

Procedure

Perform a GET request to a group resource.

/api/v1/example.org/group/<id>

This returns a application/vnd.eduserv.iam.admin.group-v1+json object.

Response codes

HTTP Response Code

Description

200

The request was successful.

400

The request was invalid.

404

The group does not exist.

Example

CODE
Request:
GET /api/v1/example.org/group/1234 HTTP/1.1
Authorization: OAApiKey <api-key>
Response (success):
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.group-v1+json
 
{
    "id": "1234",
    "name": "group1",
    "links" : [
                { "rel" : "up",
                  "type" : "application/vnd.eduserv.iam.admin.organisation-v1+json",
                  "href" : "/api/v1/example.org/organisation/1234",
                  "method" : "get"
                }
              ]
}

application/vnd.eduserv.iam.admin.group-v1+json object

Object field

Description

name

The name of the group.

Listing groups

Groups belong to and are created by organisations. Therefore an application/vnd.eduserv.iam.admin.organisation-v1+json object provides a link to a resource that will return a list of groups for that organisation.

Prerequisites

To fetch group information, a client application must

Procedure

Follow the link from an organisation object with a media type of application/vnd.eduserv.iam.admin.groupList-v1+json by performing a GET request to:

/api/v1/example.org/organisation/<id>/groups

The response payload is a list of groups.

Response codes

HTTP Response Code

Description

200

The request was successful.

400

The request was invalid.

404

The organisation does not exist.

Example

CODE
Request:
GET /api/v1/example.org/organisation/1234/groups HTTP/1.1
Authorization: OAApiKey <api-key>
Response (success):
HTTP/1.1 200 OK
Content-Type: application/vnd.eduserv.iam.admin.groupList-v1+json
 
{
    "groups": [
        { "name" : "group1", "href" : "/api/v1/example.org/group/1234" },
        { "name" : "group2", "href" : "/api/v1/example.org/group/5678" },
        { "name" : "group3", "href" : "/api/v1/example.org/group/9012" },
        { "name" : "group4", "href" : "/api/v1/example.org/group/3456" }
    ],
    "links" : [
                { "rel" : "up",
                  "type" : "application/vnd.eduserv.iam.admin.organisation-v1+json",
                  "href" : "/api/v1/example.org/organisation/1234",
                  "method" : "get"
                }
              ]
}


See also:



JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.