Skip to main content
The privy-request-expiry header allows your app to set a deadline for when an API request must be processed. Privy rejects requests where the expiry timestamp has passed, helping prevent replay attacks and the delayed presentation of previously signed requests.

​
Required headers

When using request expiry with the REST API, include the following header with your request:
​
privy-request-expiry
string
A Unix timestamp in milliseconds representing the deadline by which the request must be processed (e.g., 1773679531000).

​
When is it necessary?

The privy-request-expiry header is optional for all endpoints where authorization signatures are accepted, but strongly recommended for:
  • Requests that include authorization signatures, to limit the window in which a signed request can be used
  • State-changing operations where delayed execution could be problematic
  • Security-sensitive operations where replay attacks are a concern
If you are using Privy’s SDKs, a default expiry is automatically set when constructing authorization signatures. See more details below.

​
How request expiry works

1

Set the expiry

When making a request, include the privy-request-expiry header with a Unix timestamp in milliseconds representing the deadline for the request.
2

Include in signature payload

If the request requires an authorization signature, the privy-request-expiry header must be included in the signature payload under the headers field. The value signed must match the header value sent with the request.
3

Server-side validation

When Privy receives the request, it checks the privy-request-expiry value against the current server time. If the expiry timestamp is in the past, the request is rejected with a request_expired error.
The expiry value must be a Unix timestamp in milliseconds, not seconds. Using seconds will result in a timestamp that appears to be far in the past, and the request will be rejected.

​
Including in authorization signatures

When a request includes both a privy-request-expiry header and an authorization signature, the expiry must be included in the signature payload. This ensures that the expiry cannot be tampered with after signing. 
{
  "version": 1,
  "method": "POST",
  "url": "https://api.privy.io/api/v1/wallets/<wallet_id>/rpc",
  "body": {
    "method": "personal_sign",
    "params": {
      "message": "Hello, world!"
    }
  },
  "headers": {
    "privy-app-id": "insert-your-app-id",
    "privy-request-expiry": "1773679531000"
  }
}
See authorization signatures for the full signature payload specification.

​
Error handling

If a request is received after its expiry timestamp, Privy returns a request_expired error. See the API error codes page for details and troubleshooting steps.