Groups API endpoints

The protocol is a simple, lightweight REST-ish protocol. The group endpoints require that you provide a valid access token with scopes for appropriate attribute groups. groups-edu, groups-org and groups-other are attribute groups For different kinds of groups.

The base URL prefix of all group related endpoints on Feide is:

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

List of group protocol endpoints

Endpoint

Protocol description

Data returned

me/groups

The group memberships of the current user

List of groups

me/groups/{groupid}

My membership of this particular group

One membership object

groups/{groupid}

Details about a group

One group object

groups/{groupid}/members

Members of a group

A list of users

groups

List all groups

A list of groups

grouptypes

List all group types

A list of group types

The group memberships of the current user me/groups

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 a member of any active groups, an empty list is returned; []. If the token isn’t bound to a user, 403 Forbidden 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 specifications:

My membership of this particular group /me/groups/{groupid}

Requests need to be authenticated with a personal token.

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

GET /groups/me/groups/fc%3Aadhoc%3A8878ae43-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"
}

If the access token doesn’t allow access to the group or the token isn’t bound to a user, the endpoint returns 403 Forbidden. If the user isn’t a member of the group, 404 Not Found is returned.

Details about a group /groups/{groupid}

Requests need to be authenticated with a token.

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

GET /groups/groups/fc%3Aadhoc%3A8878ae43-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",
    "type": "voot:ad-hoc"
}

If the access token doesn’t allow access to the group, the endpoint returns 403 Forbidden. If the user isn’t a member of the group or the token isn’t bound to a user, the response from the endpoint is as follows:

Group type

Response

fc:adhoc (public)

group data

fc:adhoc (private)

404 Not Found

fc:fs

404 Not Found

fc:gogroup

404 Not Found

fc:grep

group data

fc:org

404 Not Found

Members of a group /groups/{groupid}/members

Requests need to be authenticated with a token.

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%3Aadhoc%3A8878ae43-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.

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

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

Normally, user IDs are not returned for the users when listing group members. However, when the attribute group groups-memberids is configured and the group backend supports it, the user ID is returned in a userid_sec attribute. This attribute group is moderated by Sikt. Currently, this attribute group is supported by the backend for primary and secondary education in Norway.

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"
        }
    }
]

Example, with user IDs included:

[
    {
        "name": "Alf Berg",
        "userid_sec": [
            "feide:aberg04@elgskinnetskole.sunnvik.kommune.no"
        ],
        "membership": {
            "affiliation": "student",
            "basic": "member",
            "displayName": {
                "nb": "Elev"
            }
        }
    },
    ...
    {
        "name": "Eva Vesthus",
        "userid_sec": [
            "feide:evesthus01@elgskinnetskole.sunnvik.kommune.no"
        ],
        "membership": {
            "affiliation": "student",
            "basic": "member",
            "displayName": {
                "nb": "Elev"
            }
        }
    }
]

If the access token doesn’t allow access to the group, the endpoint returns 403 Forbidden. If the user isn’t a member of the group or the token isn’t bound to a user, the response from the endpoint is as follows:

Group type

Response

fc:adhoc (public)

list of members

fc:adhoc (private)

403 Forbidden

fc:fs

both members and nonmembers receive an empty list

fc:gogroup

404 Not Found

fc:grep

both members and nonmembers receive an empty list

fc:org

both members and nonmembers receive an empty list

List all (or query a set of) groups /groups

Requests need to be authenticated with a token.

The response is a list of group objects. If no groups were found or the token isn’t bound to a user, an empty list is returned: [].

With no query string, the list contains the following groups:

There is limited support for querying.

Query string parameters (optional):

query={search}

When a query string is given, the result shown above is restricted as follows:

  • Groups of some types are dropped. Only the following types are included:

  • Groups are included when the query parameter is a substring of the displayName. For adhoc groups, matches in description also count. Search is case sensitive, except for group type fc:gogroup. Group IDs aren’t used when searching.

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

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

[
    {
        "id": "fc:adhoc:e7074db1-acb2-4165-b53e-6a48fa1019f4",
        "displayName": "Matteskatt",
        "type": "voot:ad-hoc",
        "public": true,
        "description": "Matematikk for alle."
    },
    {
        "id": "fc:gogroup:spusers.feide.no:u:NO856326499:1amat:2021-07-01:2022-06-30",
        "displayName": "Matematikk 1A",
        "type": "fc:gogroup",
        "...": "..."
    }
]

List all group types /grouptypes

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 a 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": "fc:org", "displayName": "Organization"
    },
    {
        "id": "fc:emne", "displayName": "Subject"
    }
]

Group identifiers in URLs

Group identifiers are used as path elements in URLs. The group fc:gogroup:spusers.feide.no:b:NO856326499:6a:2021-07-01:2022-07-30 represents a group in lower education in Norway. Here is how to retrieve it:

GET https://groups-api.dataporten.no/groups/groups/fc%3Agogroup%3Aspusers.feide.no%3Ab%3ANO856326499%3A6a%3A2021-07-01%3A2022-07-30

The group ID may contain ‘%’ or other special characters. You have to encode these before you use them in a URL. E.g. turn ‘6%20a’ into ‘6%2520a’.

The reason is that whenever a web server encounters a ‘%’ in a URL, it interprets it as the start of an encoded character. The urls https://www.example.org/hi and https://www.example.org/h%69 are actually the same URL. The Group API will only see a ‘%’ if it is encoded to ‘%25’.

The group ID should be percent encoded as specified in the rules for path segments in RFC 3986. The characters that do not need encoding according to this standard are ‘A-Z’, ‘a-z’, ‘0-9’, ‘-’, ‘.’, ‘_’ and ‘~’. For the groups API, ‘:’ can also be left unencoded.