Connectors for groups

Groups allow applications to use a set of group contexts for the authenticated user, for sharing, access control, communication or other purposes. These sets of groups are shared across services, minimizing the need for managing groups separately in each application.

A user is member of a set of groups. For each group the user is member of, the membership is represented with the existence of an membership object. The membership object has no required properties, but a set of optional properties.

Properties of the group object are specific for the group and are the same for all members, while properties of the membership object are specific for each member.

All groups share some common properties, while there is a set of group type definitions that define extended attributes for different kind of groups.

Here is an example of a group:

{
    "id": "fc:adhoc:3422c057-93f4-4564-831b-142ca412f970",
    "displayName": "Dataporten Pilotdeltakere",
    "description": "Utviklere og andre som deltar i Dataporten pilot 2015.",
    "type": "voot:ad-hoc"
}

The protocol and data model are using the VOOT standard, which also is used by other educational federations in Europe.

The Protocol

The protocol is a simple, lightweight REST-ish protocol based upon VOOT and SCIM. The group endpoints require that you provide a valid Dataporten OAuth 2.0 token with the groups-scope assigned.

The base URL prefix of all groups related endpoints on Dataporten is:

https://groups-api.dataporten.no/groups/

List of group protocol endpoints

EndpointProtocol descriptionData returned
me/groupsThe group memberships of the current userList of groups
me/groups/{groupid}My membership of this particular groupOne membership object
groups/{groupid}Details about a groupOne group object
groups/{groupid}/membersMembers of a group A list of users
groupsList all groupsA list of groups
grouptypesList all group typesA list of grouptypes

Requests need to be authenticated with a personal token.

This endpoint returns all active group memberships of the current user. Expired or otherwise inactive groups are not returned by default.

Query string parameters:

showAll=true
The provider will list all groups that the current user is associated with, also expired and inactive groups and roles.

The response contains a list of groups. If the user is not actively member of any groups, an empty list is returned; [].

Here is an example of a response body:

GET /groups/me/groups HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9

200 OK
Content-Type: application/json; charset=utf-8
Content-Language: no

[
	{
		"id": "fc:adhoc:8878ae43-965a-412a-87b5-38c398a76569",
		"displayName": "...",
		"...": "..."
	},
	{
		"id": "fc:adhoc:8878ae43-965a-412a-87b5-38c398a76569",
		"displayName": "....",
		"...": "..."
	}
]

For the specifications of the attributes of groups, review the group type specifiations:

Requests need to be authenticated with a personal token.

If the user is member of the specified group, this endpoint returns the membership object representing the user's relation to the group.

GET /groups/me/groups/fc:adhoc:8878ae43-965a-412a-87b5-38c398a76569 HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9

200 OK
Content-Type: application/json; charset=utf-8
Content-Language: no

{
	"basic": "member",
	"displayName": "Medlem"
}

Requests need to be authenticated with a token, if needed in order to access the content.

This endpoint returns details about a group, that the user has access to. The user might have access to view information about the group even if the user is not member. In example, the group information might be public.

GET /groups/groups/fc:adhoc:8878ae43-965a-412a-87b5-38c398a76569 HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9

200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en

{
	"id": "fc:adhoc:8878ae43-965a-412a-87b5-38c398a76569",
	"displayName": "Project on group APIs",
}

Requests need to be authenticated with a token, if needed in order to access the content.

This endpoint returns all *active* group members of the specified group. Expired or otherwise inactive members will not returned by default.

GET /groups/groups/fc:adhoc:8878ae43-965a-412a-87b5-38c398a76569/members HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9

Query string parameters:

showAll=true
The provider will list all members that are associated with the group, also expired and inactive user memberships.

Listing group members is primarily intended for display purposes, and therefore userIDs are not returned for the users.

Please get in touch with us about use cases where it is required to also include userIDs for members.

The response contains a list of users. If the group is not currently having any members, an empty list is returned; [].

Some group types does not support listing members. In these cases an empty list is returned

Here is an example of a response body:

[
	{
		"name": "Andreas Åkre Solberg",
		"membership": {
			"basic": "member"
		}
	},
	{
		"name": "Anders Lund",
		"membership": {
			"basic": "admin"
		}
	},
	{
		"name": "Olav Morken",
		"membership": {
			"basic": "member"
		}
	}
]

Requests need to be authenticated with a token, if needed in order to access the content.

This endpoint returns information about groups that the user is not neccessarily member of. It may be used for getting information about other groups that a user may choose to grant access to content in an ACL, or it may be used for initating a request to join a group.

Query string parameters (optional):

query={search}
If provided, only groups whos name matches the given query is returned.

The response contains a list of groups. If no groups was found, an empty list is returned; [].

Here is an example of a response body, to a request for the search term «UNINETT»:

GET /groups/groups?query=UNINETT HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9
[
	{
		"id": "1234-5678", "displayName": "UNINETT Systemavdelingen"
	},
	{
		"id": "1234-5689", "displayName": "UNINETT Tjenesteavdelingen"
	},
	{
		"id": "1234-5690", "displayName": "UNINETT Nettavdelingen"
	}
]

This endpoint is used to return information about group types.

It will at least return group type information for all group types represented by the groups that the current user is member of.

The response contains a list of group types. If no group types was found, an empty list is returned; [].

Here is an example of a response body:

GET /groups/grouptypes HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9
[
	{
		"id": "voot:adhoc", "displayName": "Ad-hoc group"
	},
	{
		"id": "eduorg:org", "displayName": "Organization"
	},
	{
		"id": "feide:course", "displayName": "Course"
	}
]