Licence

The licence endpoint is what premium GroupeZ plugins called at start-up to ask whether they were allowed to run. On v1 a licence was bound to three things:

• a key, generated with Str::random(15), so 15 alphanumeric characters;
• a plugin, through plugin_licences. The plugin identifies itself with its unique_id, of the form GROUPEZ_ followed by 15 lowercase hexadecimal characters;
• a list of allowed IP addresses, stored in the ips table. The seller or the customer added them by hand in the dashboard, up to max_ip.

The licence could also have an optional expiry date, expire_at (a date column).

Common behaviourCopy Anchor Link

• Base URL: https://groupez.dev/api/v1/
• Middleware: the api group, which is throttle:api, then SubstituteBindings, then TrustCloudflare. There is no session and no CSRF.
• No version header: v1 does not send X-GroupeZ-Api-Version.

POST /api/v1/licence/{key}Copy Anchor Link

Checks that a licence key exists, has not expired, belongs to the calling plugin, and is being used from an allowed IP address.

Path parametersCopy Anchor Link

Query / body parametersCopy Anchor Link

Required headerCopy Anchor Link

ResponsesCopy Anchor Link

The checks run in the order below. The first one that fails decides the answer.

1. Licence expired (expire_at is set and in the past):

{"status":"error","message":"The license has expired"}

2. unique_id missing:

{"status":"error","message":"Unable to find unique id"}

3. The key does not belong to the plugin with this unique_id:

{"status":"error","message":"Unable to find plugin for this licence"}

4. The caller's IP is not on the licence's allowed list (no ips row with adresse = CF-Connecting-IP for this licence):

{"status":"error","message":"Impossible to find the ip address"}

5. Success:

{"status":"success","message":"The license is valid"}

404 Not Found: no licence has this key. The binding fails before the controller runs. The body depends on the Accept header:

• with Accept: application/json, Laravel 8's default JSON, which names the model and the key (shown with APP_DEBUG off; the production setting is not in the repository, and with debug on exception, file, line and trace keys are added):

  Copy Text

  {"message":"No query results for model [App\\Models\\Licence] UNKNOWNKEY"}

• otherwise, the site's HTML 404 page (resources/views/errors/404.blade.php).

429 Too Many Requests: more than 60 requests per minute. Laravel 8's default ThrottleRequestsException, with Retry-After and X-RateLimit-* headers. With Accept: application/json the body is {"message":"Too Many Attempts."}. Otherwise it is an HTML error page.

405 Method Not Allowed: methods other than POST. Without Accept: application/json the answer is the HTML page errors/405. With it, Laravel 8.26's default JSON (with APP_DEBUG off):

{"message":"The GET method is not supported for this route. Supported methods: POST."}

This endpoint never returns 401, 403 or 422. Validation failures are reported as 200 with "status":"error" (see above).

ExampleCopy Anchor Link

curl -X POST "https://groupez.dev/api/v1/licence/aB3dE5fG7hI9jK1" \
  -d "unique_id=GROUPEZ_0123456789abcde"

{"status":"success","message":"The license is valid"}

NotesCopy Anchor Link

• The expiry check ignores the IP. The code reads if (expired) if (!isset($ip)) return error, but $ip is not yet defined at that point. The inner condition is therefore always true, and an expired licence is always refused, before anything else is checked.
• Expiry granularity. expire_at is a date column. Carbon::parse() turns it into midnight of that day in the app timezone (Europe/Paris), so a licence stops working at 00:00 on its expiry date, not at the end of that day.
• Side effects on success. Each successful check inserts a licence_logs row (licence_id, ip). Each request that gets past the unique_id/plugin checks also writes a warning line to the licence log channel (storage/logs/licence.log), whether or not the IP is then allowed.
• IP registration is not part of the API. Allowed IPs were added in the dashboard (Resource\LicenceController::createAdresse / createAdresseAsAdmin, limited to max_ip for the non-admin path). No API endpoint registers an IP. Both dashboard paths validate the address with ip2long(), so only IPv4 addresses could be registered: a server whose CF-Connecting-IP is an IPv6 address could never pass check 4.
• Empty unique_id. The global ConvertEmptyStringsToNull middleware turns unique_id= into null. The field is still "present" for $request->has(), so the answer is Unable to find plugin for this licence, not Unable to find unique id.
• Rate-limit key. throttle:api runs before TrustCloudflare in the api group, and the global TrustProxies trusts no proxy. Behind Cloudflare, the IP used as the throttle key is therefore probably the Cloudflare edge address, not the real client. This was inferred from the middleware order and not verified on production.
• Header spoofing. The allowed-IP check trusts the CF-Connecting-IP header as received. This is only safe if the origin server could not be reached directly, bypassing Cloudflare. Whether the legacy origin was firewalled cannot be determined from the code.
• Source files (legacy repository): routes/api.php, app/Http/Controllers/Api/LicenceController.php, app/Models/Licence.php, app/Models/Ip.php, app/Models/LicenceLog.php, app/Http/Kernel.php, app/Http/Middleware/TrustCloudflare.php, app/Providers/RouteServiceProvider.php. The legacy repository has no automated test for this endpoint.