VOOT is a simplified version of OpenSocial and the API is available at: https://voot.surfconext.nl/. The calls described below need to be prepended with this URL.
Authorization
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 access to the Voot API. For details on how this works, please refer to the SURFconext OIDC playground
Group identifier
With VOOT you can request information about a group or a user's group memberships. The groups can be from SURFconext Teams 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:collab:group:{group_provider}:{group_name}
group_provider
: name of the group provider (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:collab:group:surfteams.nl:nl:surfnet:diensten:SURFconext_admins urn:collab:group:avans.nl:nl.avans.AVANS-employee_grp
Supported calls
Get a user's group membership
/me/groups
Get group information
Group information is taken from SURFconext Teams. This call will only return the group's information if the user is a member of this group.
/me/groups/{groupId}
{groupId}
must be replaced with a SURFconext group identifier (to be obtained with the user's group membership call).
Errors
Handling failures of OAuth (Bearer) authentication are handled as described in [RFC 6750]. This will involve sending the WWW-Authenticate
header if something is wrong, for example an invalid OAuth 2.0 access token will result in the following response:
HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="Resource Server",error="invalid_token",error_description="the access token is not valid" Content-Type: application/json {"error":"invalid_token","error_description":"the access token is not valid"}
There are also some request errors defined, i.e.: invalid requests to SURFconext that are dealt with in a certain manner. The error response is returned as JSON, for example:
HTTP/1.1 404 Not Found Content-Type: application/json { "error": "invalid_user", }
Retrieve Group Membership
- If the specified user does not exist at the provider an error response with code
404 Not Found
is returned. Theerror
field containsinvalid_user
; - If any other error occurs an error response with code
500 Internal Server Error
is returned. Theerror
field containsinternal_server_error