Generate CSRF Session

The CSRF Session endpoint issues secure cookies and a public token that allow browser-based clients to safely call Paystrator API endpoints with credentials: include. This mechanism ensures requests originate from a real browser and not from automated tools (e.g., Postman, curl).

Purpose

Initializes a browser session with CSRF protection.
Sets two cookies:
- ps_csrf (HttpOnly, Secure, SameSite=None) — server-side token (not accessible by JS).
- ps_csrf_pub (Secure, SameSite=None) — public mirror token that client JS can read.
Client JavaScript must include the public token in the header X-CSRF-Token on subsequent API requests.
Server validates both the HttpOnly and public tokens (double-submit cookie pattern).
Prevents request forgery and ensures the call comes from a browser.

Request

Headers

Origin: required, must match the client’s allowed domain(s).
Content-Type: optional (application/json).
Sec-Fetch-Site / Sec-Fetch-Mode: automatically added by modern browsers.

Body

No body required.

Response

200 OK

Cookies set:

Cookie	Accessible	Secure	SameSite	Purpose
`ps_csrf`	HttpOnly	Yes	None	Server-side CSRF token (hidden from JS)
`ps_csrf_pub`	Readable	Yes	None	Public mirror token for JS to attach as `X-CSRF-Token`

Response Body:

{
    "status": 200,
    "data": {
        "csrfToken": "20250925153915978167294281056500"
    },
    "metadata": {
        "source": "API",
        "entity": "Auth"
    }
}

Example (curl with browser-like headers):

curl -X POST https://api.paystrator.com/v1/auth/clients/csrf \
  -H "Origin: https://shop.example.com" \
  --include

Cookie:

Set-Cookie: ps_csrf=...; HttpOnly; Secure; SameSite=None
Set-Cookie: ps_csrf_pub=...; Secure; SameSite=None

Response Body:

{
    "status": 200,
    "data": {
        "csrfToken": "20250925153915978167294281056500"
    },
    "metadata": {
        "source": "API",
        "entity": "Auth"
    }
}

Error Responses

Http Code	Error Code	Description
401	Unauthorized	Missing or invalid `Origin`. CSRF cookies not present. `X-CSRF-Token` mismatch.
403	origin_not_allowed	If client credentials are invalid.

Notes

Always use HTTPS: SameSite=None cookies require Secure.
CSRF tokens are short-lived (e.g., 15 minutes). Refresh by calling /v1/auth/clients/csrf again if expired.
This endpoint is generic: usable for any client-side API flow (checkout, webhooks, sandbox tools, etc.), not just payments.