Sign Partner API calls

TL;DR

With every API request header you must:

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

Overview

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).

    -H "accept: application/json" \
    -H "x-timestamp: <Epoch_timestamp>" \
    -H "x-sign: <your_generated_signature>" \
    -H "x-api-key: <your_API_key>" \
 Copy

    -H "accept: application/json" \
    -H "x-nonce: <Unique identifier>" \
    -H "x-sign: <your_generated_signature>" \
    -H "x-api-key: <your_API_key>" \
 Copy

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.

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

Construct the signature

1. Hash the private.pem with the SHA256 algorithm.

2. Sign the hash with RSA PKCS #1 1.5.

3. Encode the signature with URL-safe Base64 encoding.

Partner API Signing Client

To assist with testing your integration, Qredo 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:
  • transaction and withdrawal requests Signing Agent custody
  • requests to connect either dedicated or Multi-Counterparty Wallets to an exchange
  • sweep transactions
  • atomic swap quotes posted to the liquidity hub

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.

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
 Copy

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

   Linux/MacWindows

   You can also use this command on Windows using PowerShell:

   go build -o partnerapi-sign
    Copy

   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

   Linux/MacWindows

   You can also use this command on Windows using PowerShell:

   ./partnerapi-sign sign
    Copy

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

3. If you are sending a POST or PUT request, pass the JSON body to the next prompt.

   Sign API requests using Signing Client

   Request without a bodyRequest with a JSON body

   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):
    Copy

   There is no JSON body to add: on your keyboard, press 'Ctrl+D' twice (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 signature, and a timestamp.

   x-sign: Vc_KZBmtqdrFiGVPvDcSfmly-dK652y9kLvxSYo93hmqza_RZq1YtJXamsMAxCQTZf6JXviVLDaqtQIwjB1Jjl3ms6jyjDFC4wp0qNh9m43rNj4xY7tfoE98qzkmeTJ9BIXEvEkQtruRHsw0bG9cjQlNKmA2NtNEyquEkUsSBX1phFudvDDtIlUWqA
   x-timestamp: 1634226826
    Copy

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"
       }
     ]
   }
    Copy

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"
    }
  }
   Copy

• 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).

Sandbox testing

To simplify testing, the sandbox environment does not require the same level of security to authenticate.

For example, the following curl command will create a company:

curl -X "POST" \ 
"https://sandbox-api.qredo.network/api/v1/p/company" \ 
-H "accept: application/json" \ -H 'X-API-KEY: '$APIKEY'' \ 
-H "Content-Type: application/json" \ 
-d '{ "name": "Test2Company", "city": "Paris", "country": "FR", "domain": "company.com", "ref": "a-b-c-d-e" }'
 Copy

Where $APIKEY is the key supplied in the Web App.