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.

• How to obtain a Feide OIDC/OAuth Token

• Read more about the various Feide attribute groups

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

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

Note

In order to use endpoints starting with /v1/orgs you should read the docs on provisioning

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
/grouptypes	List all group types	A list of group types
/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

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:

• Data model: 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:

• Groups the user belongs to

• Public adhoc 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:

  • Adhoc groups (fc:adhoc)

  • Groups for primary and secondary education (fc:gogroup)

  • Organization groups (fc:org)

  • Organization unit groups (fc:orgunit)

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

Details about a group at the given organization /v1/orgs/{domain}/groups/{groupid}

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.

GET /groups/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

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

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

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 /v1/orgs/{domain}/groups/{groupid}/members

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.

Optional query string parameters:

affiliation

examples:

affiliation=student

Only return members with the given affiliation.

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

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

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

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.

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.

All groups at the given organization /v1/orgs/{domain}/groups

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.

Optional query string parameters:

go_type

examples:

go_type=a, go_type=b, go_type=u

Only return GO groups with the given group type identifier.

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.

GET /groups/v1/orgs/sunnvik.kommune.no/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: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"
        },
    }
]

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.

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

200 OK
Content-Type: application/json; charset=utf-8
Content-Language: no
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.