Skip to content


The authentication starts by sending the user to the authorization endpoint of Unidy (e.g. <tenant> with required client_id, redirect_uri, response_type and scope parameters.


A list of all OIDC endpoints can be found via the OpenID discovery endpoint at

Parameter Content
client_id Unique identifier that corresponds to one of the UIDs in Unidy's partner Applications (provided by Unidy)
redirect_uri Endpoint where the data from Unidy should be returned (must be https)
response_type One of “code”, “token” or “id_token” (the different authentication flows that correspond to the response_type parameter are described later)
scope Required: openid
Optional: email, profile, phone, address
If multiple scopes are requested, the param is a list of space (CGI escaped) separated scopes. E.g.: scope=openid+email+profile or scope=openid%20email%20profile

Claims and Scope Mapping

Access to user data is managed via the concept of scopes and claims.

Claims: A claim is a user field or user information that can be acquired. (E.g. birthdate or name).

Scopes: Scopes are used to limit an application's access to a user's account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted. In OIDC, scopes can also give access to claims. For example, for a partner site to display the full name of a user they would want access to the name claim. To get this name claim, the partner site would need to ask Unidy for the profile scope.

The following table describes the the currently available scopes and their corresponding claims. Unidy is following the OIDC specification for standard claims and scopes as closely as possible.

Scope Claims Description
open_id sub a users UNIDY_ID
email email
profile given_name family_name name gender updated_at birthdate
phone phone_number
address formatted, street_address, locality, region, country, postal_code, address_line_1, address_line_2, street, house_number, country_code, company
email_verified email_verified indicates whether an email has beed verified
active_membership active_membership any active subscription for all the subscription categories
subscriptions:read allows to read subscriptions from API
subscriptions:write allows to create, update and delete subscriptions through the API for the authorized user
subscriptions_batch:write allows to create multiple subscription through the API for the authorized user


The “sub” grant (which is provided by the mandatory open_id scope) is used for identifying the user in the partners website. These subs will be consistent with the legacy fanconnect systems sub.


In addition Unidy can create custom scopes and claims for you. Please reach out to us if you need information which is not included in the list.

An example for a userinfo response/ id_token information:

    "sub": "f2a64c72-23ec-4773-a221-b403f6c49ddc", // the unique stable identifier
    "email": "[email protected]",
    "given_name": "Mac",
    "family_name": "Mustermann",
    "name": "Max Mustermann",
    "gender": "male",
    "updated_at": "2020-11-07T13:02:10.909Z",
    "birthdate": "1983-12-08",
    "phone_number": "+49151000000012",
    "address": {
        "formatted": "Ballindamm 4\n22081\nHamburg\nDeutschland",
        "street_address": "Ballindamm 4",
        "locality": "Hamburg",
        "region": "",
        "country": "Deutschland",
        "postal_code": "22081",
        "address_line_2": "",
        "country_code": "DE",
        "company": ""


Unidy supports three of the Open id connect flows. An excellent article that describes the different flows in detail can be found here:

In a nutshell, the different flows describe in which way the partner can access the user data after it has been granted access by the user. Which flow is used is determined by the response_type parameter. Possible values for this parameter are code, token, and id_token. Which flow should be used depends on the usecase. Unidy does not make any assumptions or enforce a specific flow.

Supported Flows

Additional optional parameters

See details for paramters here

Parameter value
prompt login, none see Silent Authorization
max_age max elapsed time since last login
code_challenge generated from code_verifier see PKCE Flow
code_challenge_method plain, S256 see PKCE Flow
state RECOMMENDED! secure random value
response_mode form_post, fragment
login_hint email address of the user to be prefilled

Auto approve

Unidy follows a default authorization process where users are required to grant permission for an application to access their data. This authorization phase includes a grant page. However, if you prefer to skip this screen, you have the option to configure the Oauth application to automatically approve the requested data.