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

The group API is divided into three sections:

User groups APIs
Organization groups APIs
Other group APIs

List of group protocol endpoints#

Endpoint	Protocol description	Data returned
/me/groups	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
/v1/orgs/{domain}/groups/{groupid}	Details about a group at the given organization	One group object
/v1/orgs/{domain}/groups/{groupid}/members	All members of a group at the given organization	A list of users
/v1/orgs/{domain}/groups	List all groups at the given organization	A list of groups
/grouptypes	List all group types	A list of group types

User groups APIs#

The user groups APIs return group data for the current user. To access these APIs you must provide an access token that is bound to a user.

The group memberships of the current user#

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.

API endpoint#

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

Query string parameter#

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

Response#

The response contains a list of groups. If the user is not a member of any active 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

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "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:

Data model: Group Type specifications

Errors#

If the token isn’t bound to a user, 403 Forbidden is returned.

My membership of this particular group#

Requests need to be authenticated with a personal token.

API endpoint#

https://groups-api.dataporten.no/groups/me/groups/{groupid}

Path parameter#

groupid: The group identifier.

Response#

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

HTTP/1.1 200 OK
Content-Type: application/json

{
    "basic": "member"
}

Errors#

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#

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.

API endpoint#

https://groups-api.dataporten.no/groups/groups/{groupid}

Path parameter#

groupid: The group identifier.

Response#

Details about the group.

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

HTTP/1.1 200 OK
Content-Type: application/json

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

Errors#

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#

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.

API endpoint#

https://groups-api.dataporten.no/groups/groups/{groupid}/members

Path parameter#

groupid: The group identifier.

Query string parameter#

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

Response#

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

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

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

Errors#

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#

Requests need to be authenticated with a token.

API endpoint#

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

Response#

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: [].

The list contains the following groups:

Groups the user belongs to
Public ad hoc groups

Organization groups APIs#

The organization groups APIs allow you to retrieve group information for all groups at a given organization. To access these APIs you must provide an access token that:

Is not bound to a user.
Has the system-all-users scope.
Has the scope/attribute group (groups-org / groups-edu / groups-other) for the group information you want to retrieve.

These APIs can be used to provision users & groups without waiting for the user to log in. See the provisioning documentation for more information.

Details about a group at the given organization#

Requests need to be authenticated with a token obtained with client credentials flow.

This endpoint returns group data for a single group present in the user directory of the given organization.

API endpoint#

https://groups-api.dataporten.no/groups/v1/orgs/{domain}/groups/{groupid}

Path parameters#

domain: The Feide domain name (realm) of the organization.
groupid: The group identifier.

Response#

Details about the group.

GET /groups/v1/orgs/sunnvik.kommune.no/groups/fc%3Aorg%3Asunnvik.kommune.no HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "fc:org:sunnvik.kommune.no",
    "displayName": "Sunnvik kommune",
    "type": "fc:org",
    "orgType": [
        "primary_and_lower_secondary_owner",
        "upper_secondary_owner"
    ],
    "mail": "post@sunnvik.kommune.no",
    "norEduOrgNIN": "NO713293725",
    "eduOrgLegalName": "Sunnvik kommune"
}

Errors#

If the access token lacks the system-all-users scope, it doesn’t allow access to the the group data for the given organization, or the token is bound to a user, the endpoint returns 403 Forbidden.

All members of a group at the given organization#

Requests need to be authenticated with a token obtained with client credentials flow.

This endpoint returns all members of the given group present in the user directory of the given organization.

API endpoint#

https://groups-api.dataporten.no/groups/v1/orgs/{domain}/groups/{groupid}/members

Path parameters#

domain: The Feide domain name (realm) of the organization.
groupid: The group identifier.

Optional query string parameter#

affiliation

examples:

affiliation=student

Only return members with the given affiliation.

Response#

Members of the group.

GET /groups/v1/orgs/sunnvik.kommune.no/groups/fc%3Aorg%3Asunnvik.kommune.no/members HTTP/1.1
Host: groups-api.dataporten.no
Authorization: Bearer 0f0935c3-a997-40fb-89c2-f7da126ba5d9

HTTP/1.1 200 OK
Content-Type: application/json

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

Member user attributes are included as far as the corresponding attribute groups have been enabled:

eduPersonPrincipalName in userid-sec requires userid-feide.
name requires userinfo-name.

Errors#

All groups at the given organization#

Requests need to be authenticated with a token obtained with client credentials flow.

This endpoint returns all groups for the given organization from the user directory.

API endpoint#

https://groups-api.dataporten.no/groups/v1/orgs/{domain}/groups

Path parameter#

domain: The Feide domain name (realm) of the organization.

Optional query string parameters#

go_type

examples:

go_type=a, go_type=b, go_type=u

Only return GO groups with the specific go_type value.

grep_code

example:

grep_code=MAT0009

Only return GO groups with the given GREP code.

orgunit

examples:

orgunit=NO975279014

orgunit=U90099013

Return organization unit groups and GO groups with the given organization number. The number should be prefixed with ‘NO’ for Norwegian organization numbers and ‘U’ for foreign.

Response#

Groups at the organization.

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

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
        "id": "fc:org:sunnvik.kommune",
        "displayName": "Sunnvik kommune",
        "type": "fc:org",
        "orgType": [
            "primary_and_lower_secondary_owner",
            "upper_secondary_owner"
        ],
        "mail": "post@sunnvik.kommune.no",
        "norEduOrgNIN": "NO713293725",
        "eduOrgLegalName": "Sunnvik kommune"
    },
    {
        "id": "fc:org:sunnvik.kommune.no:unit:NO895395126",
        "parent": "fc:org:sunnvik.kommune.no",
        "displayName": "Elgskinnet skole",
        "type": "fc:org",
        "orgType": [
            "upper_secondary"
        ]
    },
    {
        "id": "fc:gogroup:sunnvik.kommune.no:b:NO895395126:vg1a:2000-07-01:2100-06-30",
        "displayName": "Basisgruppe VG1A",
        "type": "fc:gogroup",
        "notBefore": "2000-06-30T22:00:00Z",
        "notAfter": "2100-06-30T23:00:00Z",
        "go_type": "b",
        "parent": "fc:org:sunnvik.kommune.no:unit:NO895395126",
        "go_type_displayName": "basisgruppe"
    },
    {
        "id": "fc:grep2:sunnvik.kommune.no:http%3A%2F%2Fpsi.udir.no%2Flaereplan%2Faarstrinn%2Fvg1",
        "type": "fc:grep2",
        "code": "vg1",
        "grep_type": "aarstrinn",
        "displayName": {
            "nb": "Videregående trinn 1"
        },
    }
]

Errors#

Pagination#

The endpoints starting with /orgs return paged responses, with a default of 100 objects per page. A link to the next page of data is given in a Link header, like this:

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

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://groups-api.dataporten.no/groups/orgs/sunnvik.kommune.no/groups?offset=gAAAAABkGZy4M8O3T6LVKuHly5eLGYXFpAqhZEXhG8ynP_n7_E8_JAZ1BWfeq3ag49bPlJMMiXDqKORW2Fa0bmoXjtHTqkU5pZ-0PmKrCVNeZ2SA8jDiKUKlMMRxN0rN_BEb37rQk0ykv8kh47RA8ZmFRbcjcYsZb6wLdRNX0dcJVwGkaD3QGoRq85M_m3XaTiGi-93fNxkR4y86QNZ7RQ1L-8OWleKX8LgCbdEd-tFd-WwrFDUEmJrgSF83kB2YZM2o8raCflxJfS8t83U3yugxFBBLzwoq5Z4cnXv5o4_1OwuLZgpIj-Q%3D>; rel="next"

To change the page size, you can use the per_page query parameter.

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.

Other group APIs#

List all group types#

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.

API endpoint#

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

Response#

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