How to Use Request Signing

June 03, 2022 14:23

Use JWS to add an additional layer of security to every request.

When you send API requests to Paxos, you can sign the requests so that we can identify the sender. You sign requests using your own private key, similar to mTLS or SSH public authentication, and then attach the signature to the request as the Paxos-Signature HTTP header, using the JSON Web Signature (JWS) format.

See Request Signing Quickstart to get started in the sandbox.

Once request signing is enabled on your Paxos account, all requests must include a valid signature, except requests to anonymous endpoints (for example, Market Data and most Pricing requests). This ensures the request is sent by someone with a valid key and protects against in-transit tampering. Requests sent using just the Paxos API Client ID and Secret will be denied, thus signed requests add an additional layer of security. When Paxos receives the request, it verifies the signature and the request using the public key you provided. Any request with an invalid signature is denied.

To create a signed request, first generate the JWS signature with your private key using a combination of the base64url encoded header and payload, using either the EdDSA (ed25519) or ES256 algorithm. Then add your signature to the Paxos-Signature header, along with the signed header and payload, as shown in the following example:

curl -X POST https://api.sandbox.paxos.com/v2/transfer/deposit-addresses \
-H "Authorization: Bearer xRGvKetiw_phEDRnx4UgT7SrPJ9eQv-zjZthDGTYlXQ.Zx7o2uJd_
                          OitrsddSqfb1CU92rq5lhnOFHo7YtrCvss" \
-H "Paxos-Signature: eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjU0OThmNDI0LT
                     c4YWEtNDE0Yi1hNTE1LTEzOTI5ZTY5NTFkYiIsInBheG9zLmNvbS90aW1l
                     c3RhbXAiOiIxNjQ1NTAzMjcyIiwicGF4b3MuY29tL3JlcXVlc3QtbWV0aG
                     9kIjoiUE9TVCIsInBheG9zLmNvbS9yZXF1ZXN0LXBhdGgiOiIvdjIvdHJh
                     bnNmZXIvZGVwb3NpdC1hZGRyZXNzZXMifQ.eyJwcm9maWxlX2lkIjoiNDJ
                     iYjFhMmUtYTY4ZS00NGQ3LWI1ZjEtNTljY2M1YzEzZTkxIiwiY3J5cHRvX
                     25ldHdvcmsiOiJFVEhFUkVVTSJ9.7x8b_4j1dFMd1XWcmpGaf5OiyU0lo2
                     fbGlbe8epuiAJFpFziwxhhKHbc7-DaqKMV9MTTARX8VM3d2YSugPEAow" \
-d '{"profile_id":"42bb1a2e-a68e-44d7-b5f1-59ccc5c13e91", \
                  "crypto_network":"ETHEREUM" }'

Enable Request Signing

Setting up request signing depends on the environment and your account type. For all users, it’s recommended to test the configuration in the sandbox environment before implementing anything in production. If you don’t already have a sandbox account, you can create one by following the steps in the Paxos API - Getting Started guide.

If you’re a Crypto Brokerage (institutional) user, access to request signing in production must be configured by Paxos. Submit a support request or contact your Customer Success representative for more information. For testing, you can create a sandbox account and then follow the quickstart guide.

Manage Signed Requests

For production environments, you may want to create multiple API Credentials with different permissions and authentication. For example, you may want to sign all order and identity requests but not requests for historical data. To do this, you can create multiple API Credentials and then enable request signing for only those users or applications dealing with sensitive information.

Use Multiple Request Signing Keys

It’s also possible for you to simultaneously use multiple request signing keys with a single API Credential. Once you add an additional request signing key, it is immediately available for use, along with any existing key, for the API Credential. Used in this way, you can assign different request signing keys to different users or applications that use the same API Credential. This can come in handy if you need to revoke access for an application or user with a specific key: The API Credentials remain active, along with the other keys.

Rotate API Credentials

If your API Credentials needs to be changed, the Rotate Credentials option regenerates a new Secret, leaving the Client ID unchanged. When you rotate credentials, you’ll need to update any implementation that uses the Client ID. Once that’s done, your request signing keys work with the new Secret.

Next Steps

Use the Request Signing Quickstart to test signing in the sandbox.