Security
The EUIPO’s APIs use the OpenID Connect (OIDC) protocol for user authentication and application authorisation. OpenID Connect is an open authentication protocol that profiles and extends OAuth 2.0, an authorisation framework, to add an identity layer. OIDC allows clients to confirm an end user’s identity using authentication by an authorisation server.
An OAuth 2.0 server issues access tokens that client applications can use to access protected resources on behalf of the resource owner, (e.g.: create an EUTM Application on behalf of the user).
Before performing any operation with APIs, you need to obtain an authorisation token. OAuth2.0 provides various flows or grant types suitable for different types of API clients or use cases.
Some APIs may require identifying the application and the final user while the requirements of others will only be satisfied by uniquely identifying the application.
The EUIPO’s APIs that belong to the first group will specify ‘accessCode’ security flow in their security requirements ...
while APIs of the latter group will specify the ‘clientCredentials’ security flow.
However, the authorisation mechanism also allows fine grain authorisations. For instance, the user may authorise an application to apply for trade mark registrations but not design registrations. This is possible thanks to scopes.
Scope is a mechanism in OAuth 2.0 to limit an application’s access to a user’s resources.
Operations in API definitions include the required scopes in each case.
Example of EUTM Filing API where scope ‘eutm-filing.application.write’ is required to submit a new application
Identifying only the application: Application flow
Example of Trademark Seach API
You can use this security flow if the API you’re consuming does not need to know the information of the final user. An example of a request to get an Access Token using curl could be the following:
curl --location --request POST ‘https://auth-sandbox.euipo.europa.eu/oidc/accessToken’ \
--header ‘Content-Type: application/x-www-form-urlencoded’ \
--data-urlencode ‘client_id=<YOUR_CLIENT_ID>‘ \
--data-urlencode ‘client_secret=<YOUR_CLIENT_SECRET>‘ \
--data-urlencode ‘grant_type=client_credentials’
--data-urlencode ‘scope=uid’
The response should be as follows:
{
‘access_token’: ‘eyJhbGciOiJIUzI1NiJ9.eyJSb2xlIjoiVGVzdCIsIklzc3VlciI6Iklzc3VlciIsIlVzZXJuYW1lIjoiVGVzdCIsImV4cCI6MTY2OTk4MTQ1MCwiaWF0IjoxNjY5OTgxNDUwfQ._80PYR1ZX6eOPVFgtdpQNOu6vKaKVd97VI-KVAS9EhI’,
‘id_token’: ‘eyJhbGciOiJIUzI1NiJ9.eyJSb2xlIjoiVGVzdDIiLCJJc3N1ZXIiOiJJc3N1ZXIiLCJVc2VybmFtZSI6IlRlc3QyIiwiZXhwIjoxNjY5OTgxNDUwLCJpYXQiOjE2Njk5ODE0NTB9.VvkNnz0HatlYl3qwayYLs3p8PPkGM3C1KArn28DmMCE’,
‘refresh_token’: ‘RT-2022-Q2pShv8cnKEmHarxTIdW-8OqJSg7rGLG’,
‘token_type’: ‘bearer’,
‘expires_in’: 28800,
‘scope’: ‘uid’
}Identifying application and final user - Access Code
Example of EUTM Filing API
With the ‘access code’ authorisation flow, the final user never provides her credentials to the application. The application opens a browser to redirect the user to the OAuth server. The user sees the authorisation form and approves the application’s request. The user is redirected back to the application with an authorisation code that is used later by the application to ask for the access token to the authorisation server.
Step 1: Get Authorisation Code
The user needs to authorise the application to act on her behalf: At this point, the browser is redirected to the authorisation form of the Authorisation Server using an URL similar to this one :
https://auth-sandbox.euipo.europa.eu/oidc/authorize?response_type=code&client_id=
NOTE: Please note that YOUR_APP_CALLBACK corresponds with the value that you configured in OAuth Redirect URI when you registered your application in the API Portal.
The authorisation server presents the Authorisation form from where the final user authorises the application.
Once the user does the log in using her credentials, the browser is redirected to ‘YOUR_APP_CALLBACK’ URL including the authorisation code as a parameter:
Step 2: Get Access Token
Now the application can ask for the access token using the returned code as it is shown in the following example:
curl --location --request POST ‘https://auth-sandbox.euipo.europa.eu/oidc/accessToken’ \
--header ‘Content-Type: application/x-www-form-urlencoded’ \
--data-urlencode ‘client_id=<YOUR_CLIENT_ID>‘ \
--data-urlencode ‘client_secret=<YOUR_CLIENT_SECRET>‘ \
--data-urlencode ‘code=<AUTHORIZATION_CODE>‘ \
--data-urlencode ‘grant_type=authorization_code’ \
--data-urlencode ‘redirect_uri=<YOUR_APP_CALLBACK>‘Using the access token to make an API call
Once we have the access token, we can use it to make calls to the different operations offered by the APIs, as shown in the following example:
curl --location --request GET 'https://api-sandbox.euipo.europa.eu/trademark-search/trademarks?page=0&size=10' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'X-IBM-Client-Id: <YOUR_CLIENT_ID>'
Refresh token
For security reasons, access tokens have an expiration time. If the application needs to refresh the token before it expires, it should do so using a request like the following:
curl --location --request POST ‘https://auth-sandbox.euipo.europa.eu/oidc/accessToken’ \
--header ‘Content-Type: application/x-www-form-urlencoded’ \
--data-urlencode ‘refresh_token=<YOUR_REFRESH_TOKEN>‘ \
--data-urlencode ‘grant_type=refresh_token’ \
--data-urlencode ‘client_id=<YOUR_CLIENT_ID>‘ \
--data-urlencode ‘client_secret=<YOUR_CLIENT_SECRET>‘
This is especially interesting when the application uses the ‘Access code’ security flow that requires that the user interact to authorise the application to act on her behalf. Refreshing a token does not require a new user authorisation. The application simply asks the authorisation server to extend the duration of the current token.
In any case, the application could always ask for a new access token if it fits better with its use case.