Discord

These endpoints are called by Discord bots: to sign a member in with Discord, to read which resources a Discord member owns (for example to hand out roles), to grant a resource to a member, and to read the public information of a Discord server.

All of them live under https://groupez.dev/api/v1/discord.

OverviewCopier le lien vers ce titre

Common behaviourCopier le lien vers ce titre

Identifying a memberCopier le lien vers ce titre

{user} (and the discord body field) is a Discord user id (a snowflake, e.g. 123456789012345678), never a groupez.dev user id. It is resolved through the Discord account the member linked on groupez.dev (the social_accounts table, provider discord). A snowflake that nobody linked, or that belongs to a deleted account, answers 404.

HeadersCopier le lien vers ce titre

Every response of the API, errors included, carries:

X-GroupeZ-Api-Version: 1

The API is sessionless: no cookie and no CSRF token are needed. Sending Accept: application/json is recommended, although every error under /api/v1/ is rendered as JSON regardless.

Rate limitCopier le lien vers ce titre

All Discord endpoints use the api limiter: 120 requests per minute, keyed by IP address (the API carries no session, so there is no authenticated user to key on). Above the limit:

429 Too Many Requests

{
  "message": "Too many requests."
}

The Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers are forwarded when the limiter sets them.

ErrorsCopier le lien vers ce titre

Every 404 under /api/v1/ is rewritten to the same neutral body, whatever the cause (unknown member, unknown resource, closed widget):

{
  "message": "Not found."
}

Route declaration orderCopier le lien vers ce titre

Accesses payloadCopier le lien vers ce titre

POST /discord and POST /discord/{user} return the same list of accesses. Each item is spelled the way the legacy platform spelled a plugin_accesses row:

Only active accesses are listed: an access that was revoked (refund, manual revocation) is never returned. Items are ordered by id, ascending. The list is a bare JSON array, never wrapped in a data key.

GET /api/v1/discord/authenticationCopier le lien vers ce titre

Legacy entry point of the "link your Discord account" flow. On the current platform it no longer performs the OAuth exchange: it redirects the visitor to the standard Discord sign-in flow of groupez.dev.

Path parameters: none.

Query parameters: none are read. code and state sent by the legacy OAuth callback are deliberately ignored and dropped from the redirect.

ResponsesCopier le lien vers ce titre

302 Found

Location: https://groupez.dev/auth/discord/redirect

The target (oauth.redirect) then sends the visitor to Discord. That route belongs to the website, not to the API, and has its own rate limit (auth, 5 per minute).

ExampleCopier le lien vers ce titre

curl -i https://groupez.dev/api/v1/discord/authentication

NotesCopier le lien vers ce titre

• This endpoint is meant to be opened in a browser, not called by a bot.
• The redirect is a 302, not a 301, so browsers do not cache it permanently.
• An authorization code issued for the legacy callback cannot be reused: the visitor has to go through the Discord consent screen again.

POST /api/v1/discordCopier le lien vers ce titre

Returns the active accesses of a Discord member, identified by the discord body field. Despite the verb, nothing is written.

Path parameters: none.

Body parameters (JSON or form-encoded):

ResponsesCopier le lien vers ce titre

200 OK — a bare array of accesses (possibly empty):

[
  {
    "id": 42,
    "user_id": 7,
    "plugin_id": 12,
    "payment_id": 1534,
    "created_at": "2026-10-15T12:00:00.000000Z",
    "updated_at": "2026-10-15T12:00:00.000000Z"
  }
]

400 Bad Request — discord is missing, blank (only whitespace) or not a string:

{
  "message": "Discord not found"
}

404 Not Found — no account linked that snowflake (or the account was deleted):

{
  "message": "Not found."
}

429 Too Many Requests — see Rate limit.

ExampleCopier le lien vers ce titre

curl -X POST https://groupez.dev/api/v1/discord \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"discord": "123456789012345678"}'

NotesCopier le lien vers ce titre

• The controller aborts with the message User not found, but every 404 under /api/v1/ is rewritten to {"message": "Not found."}. Branch on the status code, not on the message.
• Send the snowflake as a JSON string. A JSON number ({"discord": 123456789012345678}) is not a string and answers 400; snowflakes also exceed the safe integer range of most JSON parsers.
• A member who exists but owns nothing gets 200 with [], not a 404.
• Revoked accesses are filtered out, so a refunded purchase disappears from the list.

POST /api/v1/discord/{user}Copier le lien vers ce titre

Returns a Discord member (name, groupez.dev id, avatar) together with their active accesses. Despite the verb, nothing is written.

Path parameters:

Body parameters: none.

ResponsesCopier le lien vers ce titre

200 OK

{
  "user": {
    "name": "Bobby",
    "id": 7,
    "avatar": null
  },
  "plugins": [
    {
      "id": 42,
      "user_id": 7,
      "plugin_id": 12,
      "payment_id": 1534,
      "created_at": "2026-10-15T12:00:00.000000Z",
      "updated_at": "2026-10-15T12:00:00.000000Z"
    }
  ]
}

404 Not Found — no account linked that snowflake (or the account was deleted):

{
  "message": "Not found."
}

429 Too Many Requests — see Rate limit.

ExampleCopier le lien vers ce titre

curl -X POST https://groupez.dev/api/v1/discord/123456789012345678 \
  -H "Accept: application/json"

NotesCopier le lien vers ce titre

• avatar can be null. The legacy platform always returned a URL, falling back to a default image; clients must handle null.
• No other member data is exposed (no email, role or ban state).
• GET /api/v1/discord/{id} hits a different endpoint (server information): the verb matters.

POST /api/v1/discord/{user}/apply/{resource}Copier le lien vers ce titre

Grants a resource to a Discord member. This is the only endpoint of the Discord group that writes, and it is protected by a shared secret.

Path parameters:

Body parameters:

ResponsesCopier le lien vers ce titre

200 OK — the access was granted (or a revoked access was restored):

{
  "message": "ok"
}

200 OK — the member already had an active access to this resource, nothing changed:

{
  "message": "ko"
}

403 Forbidden — the secret is missing, wrong, not a string, or no secret is configured on the server. The body never says which:

{
  "message": ""
}

404 Not Found — unknown or non-public resource, or no account linked that snowflake:

{
  "message": "Not found."
}

429 Too Many Requests — see Rate limit.

ExampleCopier le lien vers ce titre

curl -X POST https://groupez.dev/api/v1/discord/123456789012345678/apply/12 \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"custom_password": "<shared secret>"}'

NotesCopier le lien vers ce titre

• The secret is compared in constant time (hash_equals). When services.discord.purchase_secret is not set or is empty, every call is refused with 403.
• ko is not an error: it means "already owned", and the status is still 200. A bot can use it to decide whether to announce the grant.
• Calling the endpoint again is idempotent: at most one access row exists per member and resource. A previously revoked access is reactivated rather than duplicated (ok is returned in that case).
• The access is recorded with the source manual and no payment (payment_id is null in the accesses payload), so it is not counted as a sale.
• Each successful grant is written to the activity log (access.granted, via: api.v1.discord.grant) with a hashed IP address.
• The 403 body is the framework's default JSON rendering of an abort(403) without a message: with APP_DEBUG off it is {"message": ""} (the tests only assert the status and that the body leaks nothing about the secret). Rely on the status code only.

GET /api/v1/discord/{serverId}Copier le lien vers ce titre

Returns the public information of a Discord server (guild), read from its public widget.

Path parameters:

Query parameters: none.

ResponsesCopier le lien vers ce titre

200 OK

{
  "id": "987654321098765432",
  "name": "GroupeZ",
  "invite": "https://discord.gg/groupez"
}

404 Not Found — the widget is disabled, the guild does not exist, serverId is not made of digits only, or Discord could not be reached:

{
  "message": "Not found."
}

429 Too Many Requests — see Rate limit.

ExampleCopier le lien vers ce titre

curl https://groupez.dev/api/v1/discord/987654321098765432 \
  -H "Accept: application/json"

NotesCopier le lien vers ce titre

• The data comes from https://discord.com/api/guilds/{serverId}/widget.json. The server widget must be enabled in the guild settings, otherwise the answer is 404. No bot token is used.
• Only id, name and invite are returned; the member list of the widget is never forwarded.
• Successful answers are cached for 10 minutes (groupez.discord.widget_cache_seconds). Failures are not cached: enabling the widget takes effect on the next call.
• The call to Discord times out after 5 seconds (groupez.discord.timeout_seconds); a timeout answers 404.
• A serverId that is not purely numeric is rejected without calling Discord.
• GET /api/v1/discord/authentication is declared before this route and is never treated as a guild id (see Route declaration order).