Getting Started
Revision 09-FEB-2023
Prerequisite
Install OpenSSH, this comes installed by default on MacOS, and most linux distributions.
For Windows the easiest way to install is by enabling the OpenSSH feature by following the instructions here.
Generate a private Key
To get started, first generate an asymmetric ECDSA key pair.
Navigate to the directory in which the private key should be stored.
Execute the following command:
ssh-keygen -t ecdsa -b 256 -m pem -f ./{name-of-ecdsa-private-key}
Replace {name-of-ecdsa-private-key} with the name of the file you would like your private key to be stored in.
SSH keygen will prompt you for a passphrase, this can be left blank or entered depending on security needs of your organization.
When complete there will be 2 files in the directory the command was executed in:
{name-of-ecdsa-private-key} this is the private key, keep it safe do not share it. It is your digital signature.
{name-of-ecdsa-private-key}.pub this is your public key, but it needs to be converted to pem format.
Execute the following command to convert it:
ssh-keygen -f {name-of-ecdsa-private-key}.pub -e -m pem > {name-of-ecdsa-private-key}.pub.pem
This will generate a new file {name-of-ecdsa-private-key}.pub.pem
This is your public key in pem format. Share this key with Automotive Business Solutions. Automotive Busisness will use this to veify api requests were signed by the private key above.
Example public key
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEuphROC4HZxavxT1Ilb6sezZ1/Bvn
ZrGGxObLjbpCtkrRiBuqzHUO2Ua2g9/OC25FgiUe0K/G+6Tebq7Qd3bnFg==
-----END PUBLIC KEY-----
Send your public key to engineering@abswarranty.net. It will be added to your account and you will provided you with your Partner ID.
Keep the private key secure - do not send it over an insecure channel or share it with anyone, including Automotive Business Solutions.
Creating JSON Web Token
JSON Web Tokens are a standarized RFC 7519 method for sending claims in a secure manner.
Create a JSON Web Token (JWT) with the following claims:
| Name | Value |
|---|---|
| iat | (issued at) - Unix timestamp when the token was created. |
| iss | (issuer) - Your Partner ID. (Assigned by Automotive Busines Soltuions) |
| aud | (audience) - The environment Base URL. |
| exp | (expiration time) - Unix timestamp not greater than 2 hours in the future. |
For example:
{
"iat": 1627618568,
"iss": "6102b521f403f42ddcde7ae5",
"aud": "https://sandbox.absintegrations.com/api/v3",
"exp": 1627625768
}
Ensure the JWT has the correct header corresponding with the key pair algorithm.
{
"alg": "ES256",
"typ": "JWT"
}
Using the private key, sign the JWT.
The JWT will look similar to the following token:
eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2Mjc2NTU5NzAsImV4cCI6MTYyNzY2MzE3MCwiYXVkIjoiaHR0cHM6Ly9zYW5kYm94LmFic2ludGVncmF0aW9ucy5jb20vYXBpL3YzIiwiaXNzIjoiNjEwMmI1MjFmNDAzZjQyZGRjZGU3YWU1In0.y5-vxJHlBtVf2Jr9sPO4I97L5hImkhyn1EtHeCoeIzqZwObpcVy9ZEMJoCGbXwnGdeZ6GpaiO8KD9xLqgUZcTg
Verify the JWT claims and headers using jwt.io.
You are now ready to start interfacing with the Tire Protection API
Several libraries for all major languages are available to making creating and signing the JWT easy. See https://jwt.io/#libraries-io