Date: Thu, 28 Mar 2024 18:40:30 +0100 (CET) Message-ID: <410694081.7657.1711647630723@wiki01p.surfnet.nl> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_7656_1963101880.1711647630722" ------=_Part_7656_1963101880.1711647630722 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
VOOT is a simplified version of OpenSocial a= nd the API is available at: https://voot.surfconext.nl/. T= he calls described below need to be prepended with this URL.
You can use SURFconext OpenID Connect= to get an access_token. You need at least the scope "groups" to access the= Voot API. Ask SURFconext support to configure this for your client. = This access_token can be used as a bearer token to get ac= cess to the Voot API. For details on how this works, please refer to= the SURFconext OIDC playground
With VOOT you can request information about a group or a user's group me=
mberships. The groups can be from SURFconext Teams<=
/a> or an institution group provider. By default, you will not receive=
groups from an institution group provider. If you like to use=
groups from institution group provider, please contact support@surfconext.=
nl.
urn:coll= ab:group:{group_provider}:{group_name}
group_provider
: name of the group provide=
r (surfteams.nl or the name of an institution group provider, it=
has the name of that institution group provider).group_name
: name of the group=
within the group provider.urn:coll= ab:group:surfteams.nl:nl:surfnet:diensten:SURFconext_admins urn:collab:group:avans.nl:nl.avans.AVANS-employee_grp
Supported calls
/me/grou= ps
Host: voot.surfconext.nl GET /me/groups HTTP/1.1 Response HTTP/1.1 200 OK Content-Type: application/json [ { "id" : "urn:collab:group:uniharderwijk.nl:cis", "displayName" : "cis", "description" : null, "sourceID" : "UniHarderwijk", "membership" : { "basic" : "member" } }, { "id" : "urn:collab:group:surfteams.nl:nl:surfnet:diensten:myexampleteam", "displayName" : "MyExampleTeam", "description" : "This team is an example", "sourceID" : "SURFteams", "membership" : { "basic" : "admin" } } ]
Group information is taken from SURFconext Teams. This = call will only return the group's information if the user is a member of th= is group.
/me/grou= ps/{groupId}
{groupId}
must be replaced with a SURFconext group ide=
ntifier (to be obtained with the user's group membership call).
Host: voot.surfconext.nl GET /me/groups/urn:collab:group:surfteams.nl:nl:surfnet:diensten:abc_helpde= sk_administrators HTTP/1.1 Response HTTP/1.1 200 OK Content-Type: application/json =20 { "id" : "urn:collab:group:surfteams.nl:nl:surfnet:diensten:abc_helpdesk_ad= ministrators", "displayName" : "ABC helpdesk administrators", "description" : "Administrators of the ABC helpdesk service.", "sourceID" : "SURFteams", "membership" : { "basic" : "admin" } }
Handling failures of OAuth (Bearer) authentication are handled=
as described in [RFC 6750]. This will involve sending the WWW-A=
uthenticate
header if something is wrong, for example an invali=
d OAuth 2.0 access token will result in the following response:
HTTP/1.1= 401 Unauthorized WWW-Authenticate: Bearer realm=3D"Resource Server",error= =3D"invalid_token",error_description=3D"the access token is not valid" Cont= ent-Type: application/json {"error":"invalid_token","error_description":"th= e access token is not valid"}
There are also some request errors defined, i.e.: invalid requests to SU= RFconext that are dealt with in a certain manner. The error resp= onse is returned as JSON, for example:
HTTP/1.1= 404 Not Found Content-Type: application/json { "error": "invalid_user", } =
404 Not Found
is returned. The =
error
field contains invalid_user
;500 In=
ternal Server Error
is returned. The error
&nb=
sp;field contains internal_server_error