Authentication header
All API requests require three custom HTTP headers for authentication.
These headers are:
- X-dell-auth-key
- X-dell-auth-signature
- X-dell-auth-timestamp
To build the headers, perform these steps:
- Call POST /Api/V1/Authenticate.
The response includes the apiKey and apiSecret, which are required to generate the headers.
Field
|
Description
|
apiKey
|
API key required to build the request string.
Sample value: "2993d0042db9e50586b60943"
|
apiSecret
|
API secret required to compute the digest.
Sample value: "fff0bbe6ef380ef84ac2df165fd40f094ef48780728a55b9"
|
Sample JSON request:
{
"domain": "VXFMLOCAL",
"password": "admin",
"userName": "admin"
}
Sample JSON response:
{
"apiKey": "2993d0042db9e50586b60943",
"apiSecret": "fff0bbe6ef380ef84ac2df165fd40f094ef48780728a55b9",
"domain": "VXFMLOCAL",
"role": "Administrator",
"userId": 1,
"userName": "admin"
}
- Concatenate the five values listed below to create the request string:
Field
|
Description
|
apiKey
|
API key from the POST /Api/V1/Authenticate call.
Sample value: "2993d0042db9e50586b60943"
|
httpMethod
|
HTTP method, such as GET, POST, PUT, or DELETE
Sample value: "GET"
|
uriPath
|
URI path without the query parameters.
NOTE:Make sure the query parameters are not included.
Sample value: "/Api/V1/Network"
|
userAgent
|
User agent header that the client sends as part of the request.
Sample value: "rest-client/2.1.0 (linux-gnu x86_64) ruby/2.4.1p111"
|
timestamp
|
Unix timestamp for the current time.
Sample value for 2021-01-06 17:43:51 -0600: "1609976631"
|
The request string for the above sample values would be:
"2993d0042db9e50586b60943:GET:/Api/V1/Network:"rest-client/2.1.0 (linux-gnu x86_64) ruby/
2.4.1p111:1609976631"
- Compute a Base64 encoded SHA-256 HMAC digest of the concatenated request string using the apiSecret obtained from the /Api/V1/Authenticate call by performing these steps:
Step
|
Description
|
Step 1: Compute the SHA-256 HMAC digest
|
Compute the SHA-256 HMAC digest with OpenSSL. The digest is based on the apiSecret and the concatenated request string you created earlier.
Sample code:
hash_str = OpenSSL::HMAC.digest('sha256', apiSecret, requestString)
Sample execution value:
[25] pry(main)> hash_str = OpenSSL::HMAC.digest('sha256', apiSecret, requestString)
=> "!\x01p\xA6\xFF\xC2h{/\xF1\xB4\xF6\xA0/8\xA1\xD1\xAD\xF8\f\xCAG\x1E\xF3/\xCC\xA84\xD1\x02\xF2\x84"
|
Step 2: Base64 encode the HMAC digest
|
Create the Base64 encoded value that is based on the digest hash code created with OpenSSL.
Sample code:
signature = Base64.strict_encode64(hash_str)
Sample execution value:
[26] pry(main)> Base64.strict_encode64(hash_str)
=> "IQFwpv/CaHsv8bT2oC84odGt+AzKRx7zL8yoNNEC8oQ="
The signature value shown above applies to the /Api/V1/Network API call. Any call to this API should have a matching value.
|
- Set the three custom HTTP headers.
The custom HTTP headers are based on values produced by the previous steps:
Header
|
Description
|
x-dell-auth-key
|
Must be set to the apiKey
|
x-dell-auth-signature
|
Must be set to the signature
|
x-dell-auth-timestamp
|
Must be set to the timestamp
|
Here is a Ruby example that shows the process of generating the custom HTTP headers:
apiKey = '34b3577f7c3c03174a9a506b'
apiSecret = '9a6d9692ba64142e6a1934f9be994f3b0ae63959a6132c8b'
timestamp = Time.now.to_i.to_s
# Concatenate the following values
requestString = "%s:%s:%s:%s:%s" % [apiKey,httpMethod,uriPath,userAgent,timestamp]
# Compute a digest on concatenated string using apiSecret
hash_str = OpenSSL::HMAC.digest('sha256',apiSecret,requestString)
signature = Base64.strict_encode64(hash_str)
headers['x-dell-auth-key'] = apiKey
headers['x-dell-auth-signature'] = signature
headers['x-dell-auth-timestamp'] = timestamp
NOTE:If the two system clocks communicating with each other are not synchronized because of the timestamp component, authentication of future requests may fail. It is essential to synchronize the system clocks of the two systems.