Ctrl+K

Check user existence#

These endpoints allow a service to check whether a Feide user exists at an organization, without the user needing to be logged in and without retrieving any user attributes. In order to access the endpoints, a number of requirements have to be met.

Important notice: There is no guarantee that organizations delete user accounts when they are no longer in use. A positive result means the user account exists in the directory, not necessarily that the user is still active. If this distinction matters, it is recommended to communicate with the organization.

API endpoints#

By Feide ID (eppn):

https://api.dataporten.no/userinfo/v1/exists/{userid_sec}

By email address:

https://api.dataporten.no/userinfo/v1/exists-by-mail/{realm}/{mail}

Examples#

The access token has the scope system-check-user-existence in the following examples.

The Feide ID endpoint is called for the testuser with Feide ID asbjorn_elevg@testusers.feide.no like so:

curl -sSLf -H 'Authorization: Bearer ....' \
'https://api.dataporten.no/userinfo/v1/exists/feide%3Aasbjorn_elevg%40testusers.feide.no'

The email address endpoint is called for the organization testusers.feide.no and the testuser with mail asbjorn.hansen@elev.feide.no like so:

curl -sSLf -H 'Authorization: Bearer ....' \
'https://api.dataporten.no/userinfo/v1/exists-by-mail/testusers.feide.no/asbjorn.hansen%40elev.feide.no'

If a user with the provided Feide ID or email address exists at the organization, the endpoints return:

{
    "exists": true
}

If no such user exists, the endpoints return:

{
    "exists": false
}

Parameters#

userid_sec#

The userid_sec path parameter specifies the target user. This parameter contains a secondary user ID of the user, e.g. feide:user@kommune.test. Only Feide identifiers are supported.

The userid_sec must be percent encoded as specified in the rules for path segments in RFC 3986.

Example:

feide%3Auser%40kommune.test

realm#

The realm path parameter specifies the domain of the organization that the target user belongs to.

Example:

kommune.test

mail#

The mail path parameter specifies the email address of the target user.

The mail must be percent encoded as specified in the rules for path segments in RFC 3986.

Example:

user%40ansatt.kommune.test

Return values#

The endpoints return a JSON object with a single exists key. The value is

  • true if one or more matching users are found and the service is activated for the entire organization or for at least one of the users’ organizational units.

  • false if no matching user is found, or if matching users are found but the service is not activated for any of their organizational units.

Multiple users#

If multiple users are found with the provided Feide ID or email address, the endpoints return true, as they can tell that a matching user does indeed exist.

Service activation#

Even if a user exists, the response still depends on whether the service is activated for the user’s organization or organizational units. There are three possible cases:

  1. Activated for the entire organization: true

  2. Activated for at least one of the found user’s organizational units: true

  3. Activated, but not for any of the found user’s organizational units: false

If not activated for the organization at all, see Errors.

Errors#

The Feide ID endpoint returns 400 Bad Request when userid_sec does not contain a valid Feide ID. userid_sec must have prefix feide: and contain an @ symbol.

The endpoints return 401 Unauthorized when the bearer token is missing or invalid.

The endpoints return 403 Forbidden when the requirements below are not met.

Requirements for accessing the endpoints#

  • The service must have the system-check-user-existence scope.

  • The access token must have been obtained using the client credentials flow.

  • The service must be activated for the entire organization or for at least one of the organization’s organizational units.

On this page