Getting Started

Prerequisite

Install OpenSSH. This comes installed by default on most Linux distros and MacOS.

tip

For Windows users, we recommend installing Linux via WSL2.

Generate a private Key

To get started, generate an asymmetric ECDSA key pair using the P-256 curve.

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 key

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:

• key this is the private key, keep it safe and do not share it. It is used for signing JWTs.
• key.pub this is your public key, but it needs to be converted to the pem format.

Execute the following command to convert your public key:

ssh-keygen -f key.pub -e -m pem > key.pub.pem

This will generate a new file key.pub.pem.

This is your public key in the pem format. Share this key with ABS. We will use this to verify the authenticity of API requests originating from your application.

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.

caution

Keep the private key secure - do not send it over an insecure channel or share it with anyone, including Automotive Business Solutions.

Creating a JSON Web Token

info

JSON Web Tokens (JWT) are a compact, URL-safe method for sending claims which can be digitally signed. JWT is standardized in RFC 7519.

tip

Several libraries for all major languages are available to making creating and signing the JWT easy. See https://jwt.io/libraries

Create a JWT with the following claims:

Claim	Name	Description
iat	issued at	Unix timestamp when the token was created, within the last 2 hours
iss	issuer	Your Partner ID (provided by ABS)
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

tip

Verify the JWT claims and headers using https://jwt.io/#debugger-io

Make a Request

You are now ready to start making API requests.

Use the following endpoint to verify your token, substituting {JWT} with the token you generated.

Example

GET https://sandbox.absintegrations.com/api/v3/verify-token

Request

curl --location \
--request GET "https://sandbox.absintegrations.com/api/v3/verify-token" \
--header "Authorization: Bearer {JWT}" \

Response

{
  "partner_id": "63e547637976a7e05ceb2509",
  "name": "Example Partner"
}

Errors

This endpoint may respond with any documented of the status codes, however the most common error is 401: Unauthorized.

Status	Name	Description	Resolution
401	Unauthorized	The request is unauthenticated	Ensure your JWT is valid