Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

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 Block
json
json
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 Block
json
json
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:

Children Display
depth1
pageOpenAthens REST API documentation