Sign Partner API calls
TL;DR¶
With every API request header you must:
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¶
- Construct the JSON body.
- 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"}
- Hash it with the SHA256 algorithm.
- Sign the hash with RSA PKCS #1 1.5.
- 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:
- transaction and withdrawal requests Core Client 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.
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.
- Clone locally the Partner API Signing Client repo.
- Copy or move the
apikey
file to the local/partnerapi-sign
directory. - 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. - Navigate to the local
partnerapi-sign
repository. -
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¶
-
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
-
In the prompt, enter the resource
url
(do not add the HTTP method, just the URL) and press<Enter>
on your keyboard. -
The prompt that follows requires of you to paste in the JSON
body
withHTTP POST
andHTTP 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.
- Go to the Swagger UI and open the
GET /company/search
resource tab. - Select Try it out to enable editing the API call: the header parameters become available for input.
-
Copy each of the respective values of
x-timestamp
andx-sign
and paste them in the respective fields in the Swagger UI.With
POST
requests, submit the JSON body as signedIf you decide to test signing the
POST /company
resource described above (instead ofGET /company/search
), don't forget to submit the JSON body formatted exactly as when signed. -
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).