Authentication

Waltrex API uses a secure two-step token-based authentication process.

How It Works

This flow ensures that only authorized users or services can access your wallets and transactions. The process issues time-limited tokens that must be included with each API request to ensure authenticated and verified access.

Step 1: Start session

Begin the login process by calling StartSession, which returns a login session ID. This ID adds entropy and session context, helping to prevent automated login abuse and replay attacks.

Response:

JSON

{
    "data": {
        "id": "f25a279a-74b2-4739-93d0-c2b9209e24c5",
        "isCompleted": false,
        "identityType": "business-user",
        "class": "login",
        "classId": "api-email-v1",
        "activeStep": "1-auth-with-passcode",
        "expiresAt": "2025-07-01T20:16:41.181867709Z"
    }
}

• Session ID:
  • Field: id
  • Type:string (UUID v4)
  • Description: Unique session identifier used to initialize the login process. It must be included in the subsequent authentication request.
• Token expiry:
  • Field: expiresAt
  • Type: string (ISO 8601 timestamp with nanoseconds)
  • Description: The exact UTC date an~d time when the Session ID will expire.

Step 2: Authentication

Using the session ID from Step 1, submit your email and passcode to Authentication. Upon successful authentication, the API returns two tokens:

Response:

JSON

{
    "data": {
        "session": {
            "csrfToken": "abc123xyz456",
            "expiresAt": "2025-07-01T20:16:41.181867709Z",
            "token": "eyJhbGciOiJIUzI1NiIs..."
        }
    }
}

• Bearer Token:
  • Field: token
  • Description: Used to authenticate the client on all subsequent API requests. It must be included in the Authorization header using the standard Bearer schema.
• CSRF Token:
  • Field: csrfToken
  • Description: A separate token that must be sent in the x-csrf-token header with every request. This is primarily for protection against CSRF-style attacks in web or frontend contexts and is required even in token-authenticated calls.
• Token expiry:
  • Description: The exact UTC date and time when the session will expire.

Step 3: Make Authenticated API Requests

Include both tokens in every API call:

Headers:

HTTP

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
x-csrf-token: abc123xyz456

Example Request:

HTTP

GET /api/wallets/private/v1/current-vault-networks
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
x-csrf-token: abc123xyz456

Token Expiry

• Tokens expire after 24 hours.
• After expiry, repeat Steps 1 and 2 to obtain fresh tokens.

Tips

1. Always store your tokens securely (do not expose them in logs).
2. Rotate your tokens daily as part of your automation.
3. Avoid passing tokens in URLs or query parameters.