Skip to content

Authentication

Most API endpoints require requests to be authenticated via an OAuth 2.0 Bearer Token. This page explains how you can obtain a valid token that can be used for all following requests until it expires. Once the token has expired, a new one can be requested.

How to authenticate

A valid bearer token is obtained by authenticating the user with a POST request to the /authenticate/ endpoint of the Admin API.

Here's an example:

curl -i --location 'https://adminws.amica20.it/api/{version}/authenticate' \
    --header 'X-Amica20-ApplicationId: MyApp' \
    --header 'X-Amica20-ApiKey: 0e6f7b10-4de2-4140-a95f-c7f84ff5bd84' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "UserName":"user",
        "Password":"password"
    }'

HTTP/1.1 200 OK
X-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJBY2NvdW50SWQiOiIxMiIsIkRhdGFCYXNlSWQiOiIxNyIsIkRhdGFCYXNlIjoiY2xpX2MyayIsIlJvbGUiOiJhZG1pbiIsIlN1YnNjcmlwdGlvbklkIjoic3ViX3Rlc3QiLCJuYmYiOjE2OTM0OTI3OTYsImV4cCI6MTY5NDA5NzU5NiwiaWF0IjoxNjkzNDkyNzk2fQ.f4saPMxtRsKvT1ufkR80rLI3QFtT-HbDrHoKkbICJ7w
  • A 200 OK response confirms that the authentication has been successful. The response's X-Token header contains the bearer token that should be used for all subsequent requests until token expiration.
  • A 401 Unauthorized response means that authentication failed. Check that the username and password and try again.

Note

The authentication request must always include the X-Amica20-ApiKey e X-Amica20-ApplicationId headers, as shown in the example above. See the Headers page for info on required headers.

Token expiration

The authentication token has an expiration that is usually set to several days after emission.

If a request carrying a valid token is met with a 401 Unauthorized response, the current token has expired, and a new one should be obtained.

You only need to re-authenticate the user to obtain a fresh, valid token.

Required headers

Besides the token, API endpoint requests need to include special headers. For more info, please see the Headers page.