Authentication

The Europeana API supports three kinds of user authentication that are used in three different application scenarios. To perform general API calls, like search, object or provider/collection, which do not involve user-specific information, the most basic authentication scheme is used. For accessing user-specific data stored on MyEuropeana accounts using MyData calls, a caller application is to be identified by the user credentials. Finally, for applications wishing to get 3rd party access on behalf of a registered user, OAuth2 authentication scheme is supported.

Basic Authentication

This is the simplest form of authentication which does not involve accessing user-specific information. To perform a call using this authentication every API call must be provided a special authentication parameter wskey. This value of this parameter should be the public key that you got during the API user registration process. We use these keys to anonymously gather interesting statistics about API usage.

OAuth2 Authentication

For applications that wish to access MyEuropeana data of a specific end-user on his behalf, we use the standard OAuth2 authentication scheme. This scheme works by redirecting the application to a dedicated login page provided by the server and issuing to the application an authenticating token with a limited lifetime when the login is succesful. The token can be refreshed later on by the application and used in API calls which require a user token such as requesting a users profile.

Step 1: Authorize

The first step is to authorize your application to act on behalf of a specific end-user. For this you have to send the user to the authorize URL which will show a login page. Upon successful login, the user will be asked if your application can access his data on your behalf. The authorisation URL is constructed as follows:

https://www.europeana.eu/api/oauth/authorize?client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE

The CLIENT_ID is your public API key, the REDIRECT_URI is a urlencoded version of the URL you want to send the user to after a successful authorization and the SCOPE is the scope of the authorization. This can be either "read", "write" or "read write" (with a space in between).

Step 2: Retrieve and refresh the token

When the user has logged in and authorized your application successfully, he will be send back to the REDIRECT_URI as provided in step 1. The Europeana API will append the code parameter to that URI. If your redirect URI is set as domain.com/authorized the user will be redirected to domain.com/authorized?code=CODE where CODE will be the code you need to pass to the token request to request or refresh a users' token. Make sure that your application stores or caches this code value. The token request has to be constructed as follows:

https://CLIENT_ID:PRIVATE_KEY@www.europeana.eu/api/oauth/token?grant_type=authorization_code&code=CODE

Make sure your API's private key is present in the API call and that you replace CODE with the code obtained from step 1. If all has gone well, this API call will return a access_token field with the access token you can use to make API calls on behalf of this specific end-user.

Step 3: Making API calls on behalf of a user

With the access_token you can make API calls to the API on behalf of a specific end-user such as requesting someone's profile details:

https://www.europeana.eu/api/user/profile.json?access_token=ACCESS_TOKEN

References

There are many open source libraries available for various languages to help you implement this authentication scheme in your project. For more information, consult the OAuth2 reference page. A simplified overview of the OAuth process can be found here.