Versia Server Docs

Appearance

Challenges API ​

Some API routes may require a cryptographic challenge to be solved before the request can be made. This is to prevent abuse of the API by bots and other malicious actors. The challenge is a simple mathematical problem that can be solved by any client.

This is a form of proof of work CAPTCHA, and should be mostly invisible to users. The challenge is generated by the server and sent to the client, which must solve it and send the solution back to the server.

Solving a Challenge ​

Challenges are powered by the Altcha library. You may either reimplement their solution code (which is very simple), or use altcha-lib to solve the challenges.

Challenge ​

typescript
type UUID = string;

interface Challenge {
    id: UUID;
    algorithm: "SHA-256" | "SHA-384" | "SHA-512";
    challenge: string;
    maxnumber?: number;
    salt: string;
    signature: string;
}

Request Challenge ​

http
POST /api/v1/challenges

Generates a new challenge for the client to solve.

  • Returns:: Challenge
  • Authentication:: Not required
  • Permissions:: None
  • Version History:
    • 0.7.0: Added.

Example ​

http
POST /api/v1/challenges

Response ​

200 OK ​

Challenge data.

json
{
    "id":"01931621-1456-7b5b-be65-c044e6b47cbb",
    "salt":"d15e43fa3709d85ce3c74644?challenge_id=01931621-1456-7b5b-be65-c044e6b47cbb&expires=1731243386",
    "algorithm":"SHA-256",
    "challenge":"5dc6b352632912664583940e14b9dfbdf447459d4517708ce8766a39ac040eb5",
    "maxnumber":50000,
    "signature":"22c3a687dc2500cbffcb022ae8474360d5c2f63a50ba376325c211bb2ca06b7f"
}

Sending a Solution ​

To send a solution with any request, add the following headers:

  • X-Challenge-Solution: A base64 encoded string of the following JSON object:
    ts
    {
    number: number; // Solution to the challenge
    algorithm: "SHA-256" | "SHA-384" | "SHA-512";
    challenge: string;
    salt: string,
    signature: string,
}
    Example: {"number": 42, "algorithm": "SHA-256", "challenge": "xxxx", "salt": "abc", "signature": "def"} -> eyJudW1iZXIiOjQyLCJhbGdvcml0aG0iOiJTSEEtMjU2IiwiY2hhbGxlbmdlIjoieHh4eCIsInNhbHQiOiJhYmMiLCJzaWduYXR1cmUiOiJkZWYifQ==

A challenge solution is valid for 5 minutes (configurable) after the challenge is generated. No solved challenge may be used more than once.

Routes Requiring Challenges ​

If challenges are enabled, the following routes will require a challenge to be solved before the request can be made:

  • POST /api/v1/accounts

Routes requiring challenges may eventually be expanded or made configurable.