Registration

To start using the Europeana APIs you need to register for a key at the registration page. Upon registration, you will get your individual private and public authentication key. The private key (or secret) is used for specific methods that require additional authentication while the public key must be used by all other API methods, see Access using an API key.

We use these keys to gather relevant statistics about the usage of the API so that we can better improve it and be able to provide a better customer support. If abuse of these key is detected, Europeana Foundation may enforce limits to its usage or even block access to the Europeana APIs.

For this reason, we strongly recommend to not share these keys with third parties or expose it in user interfaces, code or in markup as the API keys are confidential and are for use by the client application or invidual only.

Accessing the Europeana APIs

With minor exceptions (namely Thumbnail API, OAI-PMH, SPARQL), when accessing the Europeana APIs, you need to provide your access key (corresponding to your public key) or token (issued by the Auth Service) as part of the request.

Using an API key (read-only access)

If you only want to access public information then supplying an access key is sufficient, however, if you need to access private information or contribute data to the APIs, then a token is mandatory. The preferred option to supply an access key is using the “x-api-key” header but other options are also available. If you are accesing the Europeana APIs via a browser we recommend reading this guide.

“X-Api-Key” header (preferred)

This option makes use of the standard “X-Api-Key” header to supply the key. This option is the preferred option due to its wide adoption and because it is a safer way to share your key within a request.

Request

GET https://api.europeana.eu/...
X-Api-Key: [WSKEY]

“wskey” parameter

This option makes use of the wskey parameter instead of an header. This option was the preferred and only option until 2023 but is planned for deprecation in the coming years. The reason for this change has to do with the fact that the public key can very easily be leaked when URLs are shared or bookmarked by users.

Request

GET https://api.europeana.eu/...?wskey=[WSKEY]

Using an access bearer token

This option offers access using the access tokens that are issued by the Auth Service as bearer tokens in the Authorization header. It is the preferred and most efficient way to access the Europeana APIs, however, it is for the moment restricted to a selective number of API costumers.

Request

GET https://api.europeana.eu/...
Authorization: Bearer [JWT_TOKEN]

Auth Service

The Auth Service is Europeana’s authentication and authorization service. If you are already familiared with the user accounts on the Europeana Website, you have already interacted with this service. Besides supporting the registration and management of user accounts, it can also be used as a OpenID Connect (OIDC) Provider to grant access to internal and external services such as the Europeana Website but also the Europeana APIs and, more recently, Transcribathon.eu.

If you own a service and would like to offer access using the Europeana Single Sign On (SSO), get in contact with us.

Besides offering SSO access to services using Europeana accounts, Europeana’s Auth Service also manages write-level access (by users and applications) to services that are managed by Europeana such as the Europeana APIs. In particular, APIs such as the Annotation API and User Sets API require write-level access for creating, changing or deleting resources on those APIs or to get priviledged access to access restricted resources such as private Galleries in the case of the User Sets API. Access to these APIs requires the establishment of a partnership agreement to guarantee that use conditions of the service are met.

If you would like to get write-level access to these APIs, get in contact with us.

Accessing OIDC configuration

The OIDC protocol is composed of a number of endpoints that support various functions from issuing an access token, manage user sessions and client registration, to accessing user information. The list of endpoints and available options can be viewed in the following URL.

https://auth.europeana.eu/auth/realms/europeana/.well-known/openid-configuration

Requesting a token

There are several methods to request a token depending on the level of access required or the kind of the application is requesting the token. For all these methods, the token is always requested at the following location:

https://auth.europeana.eu/auth/realms/europeana/protocol/openid-connect/token

The following methods can be offered for access:

• client credentials only

• user credentials

• authorization code flow

• refresh token

Response

Requesting a token with client credentials only

This method of requesting a token is used when the access can be granted at the level of the client application (identified by your key) and not at the user level. It is typically used for machine to machine applications.

Request

POST https://auth.europeana.eu/auth/realms/europeana/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

client_id:[CLIENT_ID]
client_secret:[CLIENT_SECRET]
grant_type:client_credentials

Requesting a token with user credentials

This method of requesting a token is used when the access can be granted at the user level and the client has access to the user credentials.

Request

POST https://auth.europeana.eu/auth/realms/europeana/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

client_id:[CLIENT_ID]
client_secret:[CLIENT_SECRET]
username:[USERNAME]
password:[PASSWORD]
grant_type:password

Requesting a token for user-level access (via authorization code flow)

This method of requesting a token is used when the access can be granted at the user level and the client has no (or it is not safe to) access to the user credentials. This method is typically used by web or mobile applications because the application's authentication methods are included in the exchange and must be kept secure.

Request

POST https://auth.europeana.eu/auth/realms/europeana/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type:authorization_code
client_id:[CLIENT_ID]
client_secret:[CLIENT_SECRET]
code:[AUTHORIZATION_CODE]
redirect_uri:[REDIRECT_URI]

Requesting a token using refresh token

This method of requesting a token is used when a refresh token has being issued as part of a previous token request.

Request

POST https://auth.europeana.eu/auth/realms/europeana/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type:refresh_token
client_id:[CLIENT_ID]
client_secret:[CLIENT_SECRET]
refresh_token:[REFRESH_TOKEN]