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 by domain name	One group object
/v1/orgs/{domain}/groups/{groupid}/members	All members of a group at the given organization by domain name	A list of users
/v1/orgs/{domain}/groups	List all groups at the given organization by domain name	A list of groups
/v1/by-orgno/{orgno}/groups/{groupid}	Details about a group at the given organization by organization number	One group object
/v1/by-orgno/{orgno}/groups/{groupid}/members	All members of a group at the given organization by organization number	A list of users
/v1/by-orgno/{orgno}/groups	List all groups at the given organization by organization number	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.

Identifying the organization#

There are two sets of organization groups endpoints that differ only in how they identify the organization.

/orgs/{domain}/...: These endpoints identify the organization by its Feide domain name (realm).
/by-orgno/{orgno}/...: These endpoints identify the organization by its 9 digit Norwegian organization number as found in Brønnøysundregistrene, corresponding to the norEduOrgNIN attribute in Feide.

Organization number resolution#

The {orgno} path parameter accepts the organization number as 9 digits with an optional case-insensitive prefix “NO”. 713293725, NO713293725, and no713293725 are all valid and refer to the same organization.

The organization number is resolved to a domain name before the request is processed. The outcome depends on how many valid domain names that are found for the given organization number:

Exactly one match: resolves to that domain name and continues just as for the corresponding /orgs/{domain}/... endpoint.
No match: returns 404 Not Found.
Multiple matches: returns 409 Conflict as the resolution was ambiguous.
Invalid organization number format: returns 400 Bad Request.

Details about a group at the given organization#

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

These endpoints return group data for a single group present in the user directory of the given organization.

API endpoints#

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

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

Path parameters#

domain / orgno: See Identifying the organization.
groupid: The group identifier.

Response#

Details about the group.

Identify organization by the domain name sunnvik.kommune.no:

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

Identify organization by the organization number NO713293725:

GET /groups/v1/by-orgno/NO713293725/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

Example of a response body:

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

403 Forbidden: The access token lacks the system-all-users scope, doesn’t allow access to the group data for the given organization, or is bound to a user.
404 Not Found: The group was not found, or the organization number does not resolve to a domain name.
409 Conflict: The organization number resolves to multiple domain names.

All members of a group at the given organization#

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

These endpoints return all members of the given group present in the user directory of the given organization.

API endpoints#

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

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

Path parameters#

domain / orgno: See Identifying 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.

Identify organization by the domain name sunnvik.kommune.no:

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

Identify organization by the organization number NO713293725:

GET /groups/v1/by-orgno/NO713293725/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

Example of a response body:

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

403 Forbidden: The access token lacks the system-all-users scope, doesn’t allow access to the group data for the given organization, or is bound to a user.
404 Not Found: The group was not found, or the organization number does not resolve to a domain name.
409 Conflict: The organization number resolves to multiple domain names.

All groups at the given organization#

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

These endpoints return all groups for the given organization from the user directory.

API endpoints#

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

https://groups-api.dataporten.no/groups/v1/by-orgno/{orgno}/groups

Path parameter#

domain / orgno: See Identifying 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.

Identify organization by the domain name sunnvik.kommune.no:

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

Identify organization by the organization number NO713293725:

GET /groups/v1/by-orgno/NO713293725/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

Example of a response body:

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

403 Forbidden: The access token lacks the system-all-users scope, doesn’t allow access to the group data for the given organization, or is bound to a user.
404 Not Found: The organization number does not resolve to a domain name.
409 Conflict: The organization number resolves to multiple domain names.

Pagination#

The organization groups endpoints 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"
    }
]