Accessing the APIs

Owned by Hugo Manguinhas
Last updated: Jun 10, 2024
4 min read

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 is used for specific methods that require additional user authentication while the public key must be used by all other API methods, see Access using an API key.

We use these keys to anonymously gather relevant statistics about the usage of the API so that we can better improve it. Please do not share these keys with third parties or expose it in user interfaces or in markup as the API keys are confidential and are for use by the client or user only.

Accessing the Europeana APIs

With minor exceptions (namely the Thumbnail API and OAI-PMH), 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.

“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 coming years.

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.

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:

The following methods can be offered for access:

  • client credentials only

  • user credentials

  • authorization code flow

  • refresh token

Response

Field

Datatype

Description

Field

Datatype

Description

access_token

String

The access token. This token is used as the Bearer token in API requests.

expires_in

Integer

The lifespan of the access token in seconds.

refresh_token

 

The refresh token. This token can be used to obtain a new access token without the need to supply the user credentials.

refresh_expires_in

Integer

The expiration time in seconds of the refresh token.

token_type

String

The type of the token. Always with value “Bearer“.

scope

String

The scopes that this token grants access to.

session_state

String

The id of the session.

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

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

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

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