API Authentication and Authorization

Avanan provides authentication and authorization sequence using Client ID and a Secret Key. These are used to obtain an API Access Token and sign all the requests sent to the API.

Note - You must have a separate API key for every region where you manage your tenants. For example, if you manage customer tenants in the US and Europe region, you need two separate API keys.

Generating API Access Token

URI - GET

To use this endpoint, send a GET request to retrieve a specific security event by its Avanan ID: /auth

Request

The request includes HTTP headers obtained while registering to the Avanan API service and calculated by the API consumer.

Request Headers

Header

Type

Required

Format

Description/Sample

x-av-req-id

String

Yes

UUID – Generated and supplied on the request.

d290f1ee-6c54-4b01-90e6

x-av-token

String

Yes

Send empty on this request only

 

x-av-app-id

String

Yes

Avanan Application ID

US:myapp29

x-av-date

String

Yes

Date-time in GMT

'2021-04-10T00:00:00.000Z'

x-av-sig

String

Yes

Calculated signature

For more details, see Calculating x-av-sig for token generation.

Calculating x-av-sig for token generation

The request includes HTTP headers obtained when you register to Avanan API service and calculated by the API consumer when you issue an API request.

To calculate the signature value (x-av-sig) for the request:

  1. Concatenate these parameters in this order:

    1. x-av-req-id

    2. x-av-app-id

    3. x-av-date

    4. Secret Key

  2. Invoke the resulting value to base 64.

  3. Do SHA-256 on the resulting value.

Example:

Let us assume the secret key is my_secret_key. Calculating the x-av-sig:

x-av-req-id: “d290f1ee-6c54-4b01-90e6”
x-av-app-id: “US:myapp29”
x-av-date: “2021-04-10T00:00:00.000Z”
Secret Key: “my_secret_key”

To calculate x-av-sig:

Copy 
sha256(
    base64(
        d290f1ee-6c54-4b01-90e6US:myapp292021-04-10T00:00:00.000Zmy_secret_key
    )
)

The resulting value is:

Copy 
sha256(
    ZDI5MGYxZWUtNmM1NC00YjAxLTkwZTZVUzpteWFwcDI5MjAyMS0wNC0xMFQwMDowMDowMC4wM DBabXlfYXZhbmFuX3NlY3JldA==
)

The resulting signature value (x-av-sig) is:

2462b23346ab0642b65d7d094aca5fb4c29fd96d0468deceae2704d258e81497

Therefore, when you send the token generation request, you must include this header:

x-av-sig: “2462b23346ab0642b65d7d094aca5fb4c29fd96d0468deceae2704d258e81497”

Request String Parameters

None

Request Body

Not applicable for GET method.

Request Sample (CURL) Format

This request sample shows URI base in USA region. For URI base in other regions, see URLs and URL Base.

Copy 
curl -X GET -H "Accept: application/json" \
    -H "x-av-req-id: d290f1ee-6c54-4b01-90e6" \
    -H "x-av-token: ‘’ " \
    -H "x-av-app-id: myapp29" \
    -H "x-av-date: 2021-04-10T00:00:00.000Z" \
    -H "x-av-sig: 2462b23346ab0642b65d7d094aca5fb4c29fd96d0468deceae2704d258e81497" \
    https://smart-api-production-1-us.avanan.net/v1.0/auth

Response

The response obtained from the service includes an HTTP response code and a token (JWT). This token is valid for 1 hour after successful authentication.

Note - You must send this token as the x-av-token header value with all the API consecutive calls.