Skip to content

Sign Partner API calls

TL;DR

With every API request header you must:

  • Authenticate: by passing the API key
  • Authorize: by passing a signature generated using your RSA key

Optional

Apply the dev toolkit Signing Client

Overview

This applies to Production only

You can skip this section for Sandbox.

In this section, you will learn how to:

  • Deploy the Partner API Signing Client
  • Start signing requests using the Partner API Signing Client

Authorize

The Qredo Partner API authorizes all requests using a signature (passed as a x-sign header), combined with a timestamp or nonce.

To facilitate your experience with signing API requests, Qredo provides the Partner API Signing Client: an example client application that generates signatures and timestamps with API calls.

Signatures in Partner API

The signature is the URL-safe Base64 encoding (RFC 4648) of the RSA PKCS #1 1.5 signature of the SHA256 hash of the payload to be signed.

The payload to be signed is the nonce or timestamp concatenated with the URL of the request and the body in compressed JSON format (if that particular call requires a body).

Use either timestamp or nonce in Partner & Core Client API calls

Pass either x-timestamp or x-nonce header with every API call.

 -H "accept: application/json" \
 -H "x-timestamp: <Epoch_timestamp>" \
 -H "x-sign: <your_generated_signature>" \
 -H "X-API-KEY: <your_API_key>" \ 

 -H "accept: application/json" \
 -H "x-timestamp: <Epoch_timestamp>" \
 -H "x-sign: <your_generated_signature>" \
 -H "X-API-KEY: <your_API_key>" \

Examples in this guide use timestamps only.

Authorization steps

  1. Construct the JSON body.
  2. Construct the request to sign in the format: [timestamp/nonce][URL][body]

Sign POST /company using a timestamp

This example uses the POST /company API call: create a company.

1639490495https://api.qredo.network/api/v1/p/company{
  "name": "ACME Corp",
  "city": "Paris",
  "country": "FR",
  "domain": "acme.com",
  "ref": "9827feec-4eae-4e80-bda3-daa7c3b97add"
}

1639490495https://api.qredo.network/api/v1/p/company{"name":"ACME Corp","city":"Paris","country":"FR","domain":"acme.com","ref":"9827feec-4eae-4e80-bda3-daa7c3b97add"}

  1. Hash it with the SHA256 algorithm.
  2. Sign the hash with RSA PKCS #1 1.5.
  3. Encode the signature with URL-safe Base64 encoding.

Send the body exactly as signed

After signing a PUT or POST request, make sure to send the JSON body formatted exactly as signed; otherwise, you will get an error.

Partner API Signing Client

To assist with testing your integration, Qreo supplies the Partner API Signing Client.

This tool, written in Golang, allows you to:

  • Sign API requests
  • Submit signed API requests to Qredo
  • Listen on a websocket URL for incoming requests to fetch:

The Signing Client source code is written in Go and is available on GitHub. You can clone or fork the repo and use its code as an example when building your custom request-signing client.

The Signing Client is for tests only

The Partner API Signing Client is provided for illustrative purposes only. Qredo does not recommend its use for operations on Production.

Install the Signing Client

To build and run the Signing Client, you must have Golang installed. Using a CLI, check if you have Golang installed by verifying the version:

go version

If you don't have Golang, install a recent stable version to proceed.

  1. Clone locally the Partner API Signing Client repo.
  2. Copy or move the apikey file to the local /partnerapi-sign directory.
  3. Copy or move your private.pem file to the /partnerapi-sign directory. Remember that you already added the public key to your account in the Qredo web application.
  4. Navigate to the local partnerapi-sign repository.

  5. Using the CLI, build the Partner API Signing Client to work with your keys:

    Build Signing Client in CLI

    You can also use this command on Windows using PowerShell: 

    go build -o partnerapi-sign

    Use command prompt: cmd.exe: 

    go build -o partnerapi-sign.exe

    The cursor moves to a new line in the CLI, and you can proceed to sign requests.

Sign requests with Signing Client

  1. Run the following command:

    Run Signing Client in CLI

    You can also use this command on Windows using PowerShell: 

    ./partnerapi-sign sign

    Use command prompt: cmd.exe: 

    partnerapi-sign.exe sign

  2. In the prompt, enter the resource url (do not add the HTTP method, just the URL) and press <Enter> on your keyboard.

  3. The prompt that follows requires of you to paste in the JSON body with HTTP POST and HTTP PUT requests.

    Sign API requests using Signing Client

    This example uses GET /company/search to retrieve all companies per account:

    » ./partnerapi-sign sign
url: https://api.qredo.network/api/v1/p/company/search
body (hit Ctrl+Z followed by <enter> to end):

    There is no JSON body to add: on your keyboard, press 'Ctrl+D' (or 'Ctrl+Z' if you're using Windows) and then Enter.

    This example uses POST /company to create a new company:

    » ./partnerapi-sign sign
url: https://api.qredo.network/api/v1/p/company
body (hit Ctrl+Z followed by <enter> to end):
{
  "name": "Randomcompanyname",
  "city": "Paris",
  "country": "FR",
  "domain": "randomcompanyname.com",
  "ref": "00-00-0a1"
}

    Prepare your JSON body and copy-paste it here. Next, on your keyboard, press 'Ctrl+D' (or 'Ctrl+Z' if you're using Windows) and then Enter.

    With either request type (with or without a JSON body), the Signing Client returns a hash value, a signature, and a timestamp.

    Hash: 3cc42895c46b50d72907879a8427859f25ddb761ee551196a38c52987c149eff
x-sign: Vc_KZBmtqdrFiGVPvDcSfmly-dK652y9kLvxSYo93hmqza_RZq1YtJXamsMAxCQTZf6JXviVLDaqtQIwjB1Jjl3ms6jyjDFC4wp0qNh9m43rNj4xY7tfoE98qzkmeTJ9BIXEvEkQtruRHsw0bG9cjQlNKmA2NtNEyquEkUsSBX1phFudvDDtIlUWqA
x-timestamp: 1634226826

Test signing requests

If you have completed all steps as described above, you can perform a final test: submit the GET /company/search request you signed just above.

  1. Go to the Swagger UI and open the GET /company/search resource tab.
  2. Select Try it out to enable editing the API call: the header parameters become available for input.

  3. Copy each of the respective values of x-timestamp and x-sign and paste them in the respective fields in the Swagger UI.

    With POST requests, submit the JSON body as signed

    If you decide to test signing the POST /company resource described above (instead of GET /company/search ), don't forget to submit the JSON body formatted exactly as when signed.

  4. Click Execute. You should get a HTTP 200 OK response with details about the company:

    {
  "total_count": 2,
  "matches": [
    {
      "company_id": "1zVKz...ebFAP",
      "name": "Company One",
      "domain": "company-001.com"
    },
    {
      "company_id": "1zXMf...U5oU5",
      "name": "Company 2",
      "domain": "company-002.com"
    }
  ]
}

You are now ready to start using the API

If you have completed all the steps, you can now begin using the Partner API.

Signing Client Gotchas

  • Testing the Signing Client is easier when you use an editor to compose, format, and edit your API requests and copy-paste them into the CLI.

  • On the step when you sign a body, after you are finished (regardless if you need to paste a body or not), make sure you do not accidentally press any other key besides 'Ctrl+D' (or 'Ctrl+Z' if you're using Windows) followed by 'Enter'. Otherwise, the signing process might be affected and submitting the API call could result in the error code HTTP 401 (bad signature).

  • With API requests that have a JSON body (e.g. every POST request), you can use uncompressed OR compressed JSON. The only rule is: if you signed compressed, then submit compressed; if you signed uncompressed, then submit exactly the same formatted JSON as the one that was signed. Otherwise, you'll get error code HTTP 401 (bad signature). 

    {
  "code": 401,
  "msg": "errPartnerAuth",
  "detail": {
    "reason": "signature"
  }
}

  • If you use a tool that formats JSON and adds tabs (as opposed to space intervals), the signature will not work, and the API call will result in error code HTTP 401 (bad signature).

Last update: 2022-12-14