API reference guide

API flow

secure connect endpoint sequence diagram
Figure 1. Secure Connect API OAuth Flow

OAuth 2.0 endpoints

Authorization endpoint

The authorization endpoint will behave in one of four ways, depending on state of the user’s MYDIGIPASS session:

  1. The user is already logged in and granted permissions to share user data with your application: If the user is logged in to MYDIGIPASS and has already agreed to share user data with your application, (s)he will be immediately redirected to your application’s redirect_uri with a valid OAuth Authorization Code.

  2. The user is logged in, but did not yet agree to share user data with your application: The user will be prompted to grant permissions to your application to access his/her MYDIGIPASS user data. After doing so, the user will be redirected to your application’s redirect_uri with a valid OAuth Authorization Code.

  3. The user is not logged in: The user will be invited to log in to MYDIGIPASS and - if needed - grant access to his/her MYDIGIPASS user data before being redirected to your application’s redirect_uri with a valid OAuth Authorization Code.

  4. The user does not have a MYDIGIPASS account: The user will be prompted to sign up for MYDIGIPASS, after which (s)he will be invited to share his/her MYDIGIPASS user data with your application before being redirected to your application’s redirect_uri.

Requests

Redirecting to the authorization endpoint using a GET request

The Secure Login Button will take care of sending users to the MYDIGIPASS authorization endpoint with a GET request.

  • HTTP Method: GET

  • URL:

https://www.mydigipass.com/oauth/authenticate?response_type=code&client_id=bfvjrkr3sxy7ik24g83ry4icu&redirect_uri=http%3A%2F%2Fyour-site.com%2Fcallback
Table 1. Parameters
Parameter Value Info

response_type

Must be set to code.

Required

client_id

A valid client_id for the configured environment.

Required

redirect_uri

A valid redirect_uri for the configured environment.

Required

Redirecting to the authorization endpoint using a POST request

The authorization endpoint supports POST requests to provide additional user details to streamline user enrollment on the MYDIGIPASS platform. This means that users don’t need to re-enter their personal details again during enrollment. This is typically implemented on a user profile page.

Instead of showing a login dialog, MYDIGIPASS will proceed directly to the sign-up page and pre-populate the signup form with the provided enrollment data. Users can also update their information before enrolling.

After enrollment, MYDIGIPASS will redirect the user agent to your application’s redirection endpoint (i.e. your callback uri) to proceed with the OAuth 2.0 protocol flow where you can retrieve the user’s MYDIGIPASS UUID and link it to your application’s user records.

GET requests are not suited to carry sensitive data that could be used to serve purposes outside the OAuth 2.0 protocol, because GET requests and all their application/x-www-form-urlcoded parameters end up in browser histories and application logs. For this reason, the OAuth 2.0 authorization endpoint also supports POST request.

To redirect the user to the authorization endpoint with a POST request, you must construct an HTML form that is submitted to our authorization endpoint. You can make this transparent for end-users by using a hidden form and submit it when the user requests to connect his / her account to MYDIGIPASS. You could also automatically submit the form via Javascript.

Tip

Implementing the HTML form only makes sense if you have at least the user’s first name, last name and email details to streamline enrollment. If you have less details, use the standard Secure Login Button.

HTML Form specification:

Parameter Value Info

method

Must be set to post.

Required

action

https://www.mydigipass.com/oauth/authenticate

Required

accept-charset

Must be set to UTF-8.

Required

enctype

Must be set to application/x-www-form-urlencoded.

Required

Input field specification:

Use input fields with enrollment_data[a_field_name] as the value of the name attribute:

<input type="text" name="enrollment_data[a_field_name]" value="a_value" />

Enrollment data parameters specification:

The list of possible parameters and how they are used on the MYDIGIPASS signup page.

Parameter Description

first_name

The first name of your user. Users are required to provide their first and last name to MYDIGIPASS. You can also use this parameter if your application stores the first and last name as one field.

last_name

The last name of your user. Required by MYDIGIPASS. Omit if your application stores the first and last name as one field.

email

The email of your user required to log in to MYDIGIPASS.

birth_date_year, birth_date_month, birth_date_day

The birthday of the user, separated in date parts. Legal requirements might restrict usage of MYDIGIPASS to a certain minimum age, depending on the geographic location of the user’s place of residence.

address_1, address_2 zip, city, country

Address parameters are not pre-populated on MYDIGIPASS at the time of writing, but probably will be in the near future. Include them in your code if you have the information available and want it to be picked up in the future.

Example HTML form:

<form action="http://www.mydigipass.com/oauth/authenticate" method="post" accept-charset="UTF-8">
    <!-- OAuth parameters -->
    <input type="text" name="response_type" value="code" />
    <input type="text" name="client_id" value="5tebn0q12kv52mqnwcdhk0mu7" />
    <input type="text" name="redirect_uri"
           value="http://10.32.64.191:5555" />
    <!-- enrollment-data parameters -->
    <input type="text" name="enrollment_data[first_name]" value="Anna" />
    <input type="text" name="enrollment_data[last_name]" value="Smith Jones" />
    <input type="text" name="enrollment_data[email]" value="an@yopmail.com" />
    <input type="text" name="enrollment_data[birth_date_year]" value="1980" />
    <input type="text" name="enrollment_data[birth_date_month]" value="08" />
    <input type="text" name="enrollment_data[birth_date_day]" value="15" />
    <input type="text" name="is_sandbox" value="true" />
    <input type="submit" value="Submit">
</form>

Redirect URI endpoint

This is the URL of your application where MYDIGIPASS users are redirected to after logging in to MYDIGIPASS i.e. the redirect_uri you entered when your registered your application and configured in the data-redirect-uri attribute of the Secure Login Button.

Request

  • HTTP Method: GET

  • URL:

https://your-app.com/mydigipass/callback?code=f5viowxggzn6ad02av856bfy&state=http%3A%2F%2Fyour-app.com%2Fuser-profile
Table 2. Parameters
Parameter Value

code

The OAuth Authorization Code.

state

The exact value as configured in the data-state attribute of the Secure Login Button. Use it so your application remembers that a user pressed the Secure Login Button on your application’s user profile page and to prevent CSRF attacks.

When your redirection endpoint is called, you initiate the back-channel requests towards the token endpoint, the user data endpoints and - if applicable - the connect or disconnect endpoints to conclude the Secure Connect API flow.

Caution

If you redirect your users to an URL you receive in the state parameter, it must be evaluated to ensure it’s the same URL you configured in the data-state attribute of the Secure Login Button. Otherwise your redirection endpoint becomes an open redirector and this is a serious security risk. See http://tools.ietf.org/html/draft-ietf-oauth-v2-22#section-10.15 for more information about open redirectors.

Errors

In cases where the Secure Login Button was not properly configured (e.g. a missing parameter), we will redirect the user to your application’s redirection endpoint and include information about the error in the error & error_description parameters.

Example error callback:

https://your-app.com/callback?error=invalid_request&error_description=Missing+required+parameter+redirect_uri

Token endpoint

Your application exchanges the OAuth Authorization Code for a time-limited OAuth Access Token and the UUID of the user at the token endpoint.

Request

  • HTTP Method: POST

  • Content-Type: application/x-www-form-urlencoded

  • URL:

https://www.mydigipass.com/oauth/token
Table 3. Parameters
Parameter Description

code

The OAuth Authorization Code passed to your application’s redirect_uri.

client_id

The client_id assigned to your application during registration.

client_secret

The client_secret assigned to your application during registration.

redirect_uri

The callback redirect_uri you configured for your application during registration.

grant_type

You must set this value to authorization_code as defined in the OAuth 2.0 specification.

Responses

200 Ok
  • Content-type: application/json

  • Response fields in JSON hash:

Key Value

uuid

The UUID which must be stored in your application’s user record to identify the MYDIGIPASS user.

access_token

A time-limited OAuth Access Token to use at the various data endpoints to retrieve MYDIGIPASS user data. Note that there are separate endpoints for eID and user-provided data.

scope

The type of data which can be retrieved with a valid OAuth Access Token is determined by the authorization scope parameter.

Note

Retrieving the UUID at the token endpoint is considered a successful MYDIGIPASS authentication.

You now have the information needed to consider the user as authenticated by comparing the UUID in the response with the one in your own user database and start an application session for the user.

400 Bad Request
  • The request was malformed e.g. missing a required parameter or a value was incorrect.

  • Content-type: application/json

  • Error fields in JSON hash:

Key Value

error

Short key, e.g. redirect_uri_mismatch.

error_description

Full description e.g Parameter redirect_uri does not match registered URI.

500 Internal Server Error
  • The server encountered an unexpected condition which prevented it from fulfilling the request.

  • Retry the request at a later time.

Data endpoints

OAuth Authorization scopes

Requesting permission to access specific user data - like the eID data - is done by using authorization scopes in any request to our authorization endpoint. This is done via the scope request parameter. Multiple scopes can be specified as a space-delimited list.

Table 4. eID authorization scopes
Scope value Description

eid_profile

Electronic identity profile of a user with a valid eID card.

eid_address

The user’s home address as encoded on the electronic ID.

eid_photo

The user’s photograph as encoded on the electronic ID.

Will allow access (via access token) at relevant data at the eID data and eID photo data endpoints (see accessing data below).

Table 5. User data authorization scopes
Scope value Description

email

The user’s confirmed e-mail address. You might not receive the users' email when the user has not yet confirmed his/her e-mail address.

phone

The user’s confirmed phone number. You might not receive the users' phone number when the user has not yet confirmed his/her phone number.

profile

Regular profile of the user

address

The address of the user

Will allow access (via access token) at relevant data at the user data endpoint (see accessing data below).

Example request

This example asks the user for access to his email and phone number via the scope parameter: scope=email phone

https://www.mydigipass.com/oauth/authenticate?response_type=code&client_id=bfvjrkr3sxy7ik24g83ry4icu&redirect_uri=http%3A%2F%2Fyour-app.com%2Fcallback&state=XYZ4321&scope=email%20phone

If the user accepts this request, you will receive an authorization code on your redirect uri which you can then exchange for an access token at the token endpoint.

Access denied

The user can deny any request for his data. When this happens you will be notified of this on your redirect uri endpoint:

https://your-app.com/callback?error=access_denied&error_description=The+user+denied+the+request&state=XYZ4321

Accessing data

Granted scopes

When exchanging an authorization code for an access token at our token endpoint you will receive an access token, the users' UUID and a list of granted scopes:

Example token endpoint application/json response body:

{
  "access_token" : "Tga0VZP17kzyODPrAqyaM8pApILb68yDen05PDbF",
  "uuid" : "7d092960-f776-0130-6960-28206654eb77",
  "scope" : "email phone_number"
}

You can use the value of scope to determine which data endpoint to access with the access token.

When a user grants you access to his data any access token can be used at a data endpoint for which access was granted. If you use an access token at an endpoint for which no access was granted you will receive a 401 Unauthorized error.

Use the time-limited OAuth Access Token at the user data endpoint to get more information about a MYDIGIPASS user. Include the OAuth Access Token in the Authorization header as a Bearer token.

User data endpoint

Relevant for granted scopes: email, phone, profile, address.

Request
  • HTTP Method: GET

  • Content-Type: N/A

  • Authorization: Bearer {ACCESS_TOKEN}

  • URL:

https://www.mydigipass.com/oauth/user_data
Responses
200 Ok
  • Content-type: application/json

  • UUID & email, phone_number and profile information in JSON hash.

eID data endpoint

Relevant for granted scopes: eid_profile, eid_address

Request
  • HTTP Method: GET

  • Content-Type: N/A

  • Authorization: Bearer {ACCESS_TOKEN}

  • URL:

https://www.mydigipass.com/oauth/eid_data
Responses
200 Ok
  • Content-type: application/json

  • eID profile and/or eID address information in JSON hash.

401 Unauthorized
  • The Authorization header was missing, malformed; the OAuth Access Token expired or the eid_profile or eid_address scopes weren’t granted.

  • Content-type: application/json

  • Error description in JSON hash

eID photo data endpoint

Relevant for granted scopes: eid_photo

Request
  • HTTP Method: GET

  • Content-Type: N/A

  • Authorization: Bearer {ACCESS_TOKEN}

  • URL:

https://www.mydigipass.com/oauth/eid_photo_data
Responses
200 Ok
  • Content-type: image/jpeg

  • Body: binary representation of eID photo

401 Unauthorized
  • The Authorization header was missing, malformed; the OAuth Access Token expired or the eid_photo scope wasn’t granted.

  • Content-type: application/json

  • Error description in JSON hash

Revoking access to a token or application

At any time, a user can revoke access to any scope for any application. When exchanging an authorization code for an access token, this will be reflected in the value of the scope.

Example:

A user removes his eID card authenticator and as such his eID profile. This will remove the eid_profile, eid_address and eid_photo granted scopes for your application.

User accounting endpoints

The user accounting endpoints allow your application to keep track of users that are linked to MYDIGIPASS. These endpoints are not an intrinsic part of the OAuth 2.0 Secure Connect API flow and only exist to support user accounting actions. Note that the connect endpoint must be called at least once for every user in your database.

user accounting sequence diagram
Figure 2. User Accounting API

Connect endpoint

When signing up a new user or connecting a UUID with an existing account for the first time you have to call the connect endpoint. Call the connect endpoint at least once for every MYDIGIPASS user.

Request
  • HTTP Method: POST

  • Content-Type: application/json

  • Use Basic authentication with client_id and client_secret as username/password.

  • Include the UUID to connect in the JSON body e.g. {"uuids" : ["7d092960-f776-0130-6960-28206654eb77"] }

  • URL:

https://www.mydigipass.com/api/uuids/connected
Responses
201 Created
  • The UUID was successfully connected to your application.

401 Unauthorized
  • The Authorization header was missing, malformed or wasn’t properly configured for Basic authentication with a valid client_id and client_secret as username/password.

500 Internal Server Error
  • The server encountered an unexpected condition which prevented it from fulfilling the request.

  • Retry the request at later time.

Disconnect endpoint

When deleting a user or removing MYDIGIPASS as his authentication mechanism you have to call the disconnect endpoint.

Request
  • HTTP Method: POST

  • Content-Type: application/json

  • Use Basic authentication with client_id and client_secret as username/password.

  • Include the UUID to disconnect in the JSON body e.g. {"uuids" : ["7d092960-f776-0130-6960-28206654eb77"] }

  • URL:

https://www.mydigipass.com/api/uuids/disconnected
Responses
201 Created
  • The UUID was succesfully disconnected to your application.

401 Unauthorized
  • The Authorization header was missing, malformed or wasn’t properly configured for Basic authentication with a valid client_id and client_secret as username/password.

500 Internal Server Error
  • The server encountered an unexpected condition which prevented it from fulfilling the request.

  • Retry the request at later time.

Connected users endpoint

A list of connected UUIDs can be compared with your database to correct problems by connecting or disconnecting these UUIDs from MYDIGIPASS.

Request
  • HTTP Method: GET

  • Content-Type: application/json

  • Use Basic authentication with client_id and client_secret as username/password.

  • URL:

https://www.mydigipass.com/api/uuids/connected
Responses
200 Ok
  • The JSON response body contains a list of connected UUIDs e.g.:

{:uuids=>["7d092960-f776-0130-6960-28206654eb77"]}`
401 Unauthorized
  • The Authorization header was missing, malformed or wasn’t properly configured for Basic authentication with a valid client_id and client_secret as username/password.

500 Internal Server Error
  • The server encountered an unexpected condition which prevented it from fulfilling the request.

  • Retry the request at a later time.