Request signing must be activated by Paxos. Contact Support to get started.Signed requests use 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.
Set Up Signed Request
To get started, you will need to have the Client ID and Secret available for constructing the payload. Additionally, install the JOSE/JWS library in the language of your choice, for example PyJWT which includes support for crypto.Never share your private keys with anyone, especially for Production deployments. Using an HSM, secrets manager, or key-management service may provide an additional layer of protection.
➊ Generate Key Pair
Generate the JWS signature with your private key using a combination of the base64url encoded header and payload, using either the EdDSA (ed25519) or the ES256 algorithm.To use the EdDSA (ed25519) algorithm when generating key pairs, install OpenSSL 3 using the package manager of your choice. Older versions of OpenSSL do not support the EdDSA (ed25519) algorithm.To generate a new ES256 private key using the terminal:
- Ensure OpenSSL 3 is installed:
openssl version
- Create a new ES256 private key in the current working directory:
openssl ecparam -name prime256v1 -genkey -noout -out my-private-ec.pem
- Generate the public key in the current working directory:
openssl ec -in my-private-ec.pem -pubout > my-public-ec.pem
- Ensure OpenSSL 3 is installed:
openssl version
openssl genpkey -algorithm ed25519 -outform PEM -out my-private-key.pem
openssl pkey -in my-private-key.pem -pubout > my-public-key.pem
Never share your private keys with anyone, especially for Production deployments. Using an HSM, secrets manager, or key-management service may provide an additional layer of protection.
➋ Add Public Key to Your Paxos Account
Go to Admin > API in either [Sandbox][admin-api-sandbox] or [Production][admin-api-production] and find the API Credentials that require request signing. Go to ** Admin > API** in either Sandbox or Production and find the API Credentials that require request signing.Request signing must be activated by Paxos. Contact Support to get started.Scroll down and use Edit API Credentials to make changes. Switch Request Signing to open the edit dialogue and add your Public Key. Once you Save Changes, contact Support to get started.
➌ Generate Signed Request
Use a JOSE/JWS library such as PyJWT to generate the signature.Construct Header
The header must include the following:Header Item | Description |
---|---|
kid | The Key ID of the configured Public Key. Retrieve from Admin > API > API Cretentials. |
alg | The algorithm used to generate the Key. The value must be: EdDSA or ES256. Retrieve from Admin > API > API Cretentials. |
paxos.com/timestamp | The current timestamp in UNIX time format. Signatures remain valid for 30 minutes after the specified timestamp. |
paxos.com/request-method | The POST and PUT methods also require the JWS payload in the body bytes. |
paxos.com/request-path | The endpoint path, including query parameters. |
POST
or PUT
method, include the JWS payload in the body bytes:
Create Signature
Use a library such as PyJWT to generate the request signature. First, install the library and start a new session. For example:➍ Send Signed Request
Use the generated signature to send a signed request to Paxos. First, authenticate with the APIs. For example: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 is 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 will need to update any implementation that uses the Client ID. Once that is done, your request signing keys work with the new Secret.