Spot alt accounts before they reach your server

What the Verify API solves

A banned user comes back with a fresh account, and all your bot sees is a new Discord ID. The Verify API gives you a second angle: it recognises the device, not the account.

Quickstart

Four steps from nothing to your first verdict.

1. Register your bot

   Create a verify tenant for your bot in the dashboard. That gives you your signing secret and the field for your webhook URL.

2. Create an API key

   Generate a key. You see it exactly once, after that only the prefix. Up to 5 keys can be active per tenant at the same time.

3. Create a session

   When a user needs to verify, your bot creates a session and sends them the verifyUrl it gets back, for example by DM or behind a button.

   curl Copy

   curl -X POST https://mrs-maid.cc/api/verify/v1/session \
     -H "Authorization: Bearer mm_vrf_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"guildId":"123456789012345678","userId":"987654321098765432"}'

4. Receive the result

   If you configured a webhook URL, the verdict is delivered to you automatically. Otherwise, or when a delivery fails, you fetch the session through the polling endpoint.

The verify flow

How one verification runs end to end. Steps one and two are one-off, three through nine happen per user.

1. Register the bot in the dashboard

   You create a verify tenant. It holds your signing secret, your webhook URL and your plan.

2. Create an API key

   The key identifies your bot to the API and is also the unit that quota and burst limit are counted against.

3. Create a session

   Your bot calls the session endpoint with guildId and userId and gets back sessionId, verifyUrl and an expiry. By default the link is valid for 900 seconds.

4. The user opens the link

   You deliver the verifyUrl to the user, for example by direct message or through a button. The link is issued for exactly that user and that server.

5. Consent screen

   In the browser the user first sees what is collected and why. Nothing else happens without their agreement.

6. Discord login

   The user signs in with Discord. If a different account signs in than the one named in the link, the flow stops with an error.

7. Device check and optional captcha

   The browser collects the fingerprint. If you requested a captcha for this session and your plan allows it, it is solved here.

8. Verdict and webhook

   The result is computed, reduced to the fields of your plan and sent to your webhook URL. The user sees a completion page immediately, no matter how fast your endpoint answers.

9. Act on the result

   Your bot processes the verdict from the webhook or fetches it through the polling endpoint, and then decides on its own whether to grant a role, flag a case for review, or kick.

Endpoints

Three endpoints, and the integration needs nothing more. All responses are JSON and are never cached.

curl https://mrs-maid.cc/api/verify/v1

{
  "name": "Mrs. Maid Verify API",
  "version": "v1",
  "docs": "https://mrs-maid.cc/verify-api",
  "usage": "POST /api/verify/v1/session with header \"Authorization: Bearer <key>\" and body {guildId,userId}."
}

curl -X POST https://mrs-maid.cc/api/verify/v1/session \
  -H "Authorization: Bearer mm_vrf_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "guildId": "123456789012345678",
        "userId": "987654321098765432",
        "captcha": true,
        "meta": { "ticket": "a1b2c3" }
      }'

{
  "sessionId": "vsess_3f1c8a9e-2d44-4b17-9c0a-7e15b0a2d9f1",
  "verifyUrl": "https://mrs-maid.cc/verify/s/eyJ0Ijoi...<token>",
  "captcha": true,
  "expiresAt": 1785312000
}

curl -H "Authorization: Bearer mm_vrf_YOUR_KEY" \
  https://mrs-maid.cc/api/verify/v1/session/vsess_3f1c8a9e-2d44-4b17-9c0a-7e15b0a2d9f1

{
  "sessionId": "vsess_3f1c8a9e-2d44-4b17-9c0a-7e15b0a2d9f1",
  "status": "pending",
  "guildId": "123456789012345678",
  "userId": "987654321098765432"
}

{
  "status": "completed",
  "event": "verify.completed",
  "sessionId": "vsess_3f1c8a9e-2d44-4b17-9c0a-7e15b0a2d9f1",
  "guildId": "123456789012345678",
  "userId": "987654321098765432",
  "meta": { "ticket": "a1b2c3" },
  "completedAt": 1785311640,
  "isVerified": true,
  "isInDiscord": false,
  "isAlt": false,
  "altUserIds": [],
  "trustScore": 82,
  "signals": ["alt_shared_ip", "bot:no_gpu"],
  "penalties": { "alt": 0, "privacy": 5, "bot": 0 },
  "telemetry": {
    "ipHash": "9f2c...",
    "country": "DE",
    "asn": "3320",
    "asnOrg": "Deutsche Telekom AG",
    "rttMs": 24,
    "gpuSpeedMs": 11
  },
  "captchaPassed": true
}

Result fields

Webhook and polling return the same structure. Which fields are included depends on your plan: a higher plan adds fields, it does not change the existing ones.

How to read the fields

Plans and limits

Plans differ in two things: how many sessions you may create per day, and how detailed the result is.

Pro and Scale return exactly the same fields. The only difference is the daily limit.

Current prices are in your dashboard, where you also see your active plan and your usage. Go to verify keys

Rate limits and quota

Three layers apply independently. When one of them fills up you get a 429, no matter how much room is left in the others.

Headers

There are two families of headers. X-RateLimit-* describes your daily quota and appears only on responses from POST /session, including the successful ones. The draft-7 headers belong to the IP limit and appear on every endpoint, so on the polling call and the service info as well.

Errors

Errors always come back as JSON with an error field. The machine-readable code is stable, the message next to it may change. Branch on the code, not on the text.

Privacy and retention

Verification processes personal data. We keep it as briefly as possible and only hand it out at the depth your plan provides for.

Ready for your first test run

Register your bot, create a key and open your first session. The free plan is enough to walk through the whole flow once.