Permissions, errors and limits

Permissions (scopes)

A client asks for permissions when it is registered; the member sees them on the consent page.

Scope	Who	What
profile:read	member	GET /v1/me — name, e-mail, contacts, particulars of birth, the fiscal code when there is one, and how the person is identified (codicefiscale_check)
profile:write	member	PATCH /v1/me — phone, gender, and the identification: date, place and country of birth, fiscal code (optional, may be added later; re-validated)
membership:read	member	GET /v1/me/membership, /events, /statuto, /card
membership:request	member	POST /v1/me/membership — membership request
statuto:accept	member	POST /v1/me/membership/statuto/accept
network:manage	member	the member’s consent to circuits (coming soon)
memberships:read	client	GET /v1/memberships/{id}/status
verify:read	client	card verification beyond the anonymous quota
identity:signup	client	POST /v1/signup — create accounts on behalf of members (server integrations)
enroll:write	client	POST /v1/enroll — submit membership requests, with or without a fiscal code (guide)
events:read	member	GET /v1/events, /v1/events/{slug}, /eligibility — members-only events included (guide)
registrations:read	member, client	GET /v1/me/registrations (member); GET /v1/events/{slug}/registrations (client, no personal data)
registrations:write	member, client	POST /v1/events/{slug}/registrations and DELETE /v1/me/registrations/{id} (member); POST …/registrations/guest (client)
checkins:write	client	POST /v1/checkins — door check-ins from a card or a registration
webhooks:manage	client	coming soon

A public or native client may only ask for member permissions; “client” permissions require a confidential client. Someone who is not a member yet may only grant the enrolment permissions (profile:*, membership:read, membership:request, statuto:accept).

Errors

Error responses are application/problem+json (RFC 9457):

{
  "type": "https://developers.vimine.network/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "Missing scope: profile:write",
  "request_id": "…"
}

code is stable: branch on that. errors[] accompanies validation_failed and identification_required ({ field, code }). A codicefiscale_mismatch entry — a fiscal code that disagrees with the person’s particulars — also carries mismatches, hints and confirmable: when confirmable is true the person may confirm the code and the request is repeated with codicefiscale_confirmed: true (see Members without a fiscal code). The OAuth endpoints (/v1/oauth/token, /revoke) answer in the OAuth format ({ error, error_description }).

code	Meaning
missing_token, invalid_token, token_expired	401 — sign in again (the SDK refreshes and retries by itself)
insufficient_scope	403 — the token lacks that permission
api_disabled	403 — the association has not enabled the API or does not accept requests
plan_limit	403 — the association’s plan has no room for one more member (check aps.accepting_requests before showing the form)
not_available	403 — the association does not take requests right now: it has not accepted the platform’s agreements or registered its statuto yet, it is not ready, or it takes only the people it invited (the private beta); detail says which. On POST /v1/signup: during the beta, accounts are created by invitation
not_found	404 — also for resources of other associations
validation_failed	422 — see errors[] (required, invalid, invalid_codicefiscale, codicefiscale_mismatch with confirmable…)
identification_required	422 on POST /v1/me/membership, 409 on POST /v1/enroll/confirm — the person is not identified: a fiscal code, or date, place and country of birth, is needed; errors[] names what is missing
statuto_outdated, statuto_required	422 — indicates the in-force statuto version (detail)
rate_limited	429 — wait Retry-After
unavailable	503 — retry shortly

OAuth: invalid_grant (code or refresh token invalid, expired or reused), invalid_client, invalid_scope, unauthorized_client (client awaiting activation), access_denied (the member cancelled).

In the SDK all of this is a VimineError with the same code.

The private beta

Vimine is in a private beta: people and associations come in by invitation. For a client this means:

• POST /v1/signup answers 403 not_available and creates nothing, unless Vimine has opened your association’s public enrolment;
• an association that takes only the people it invited has aps.invitation_only: true and aps.accepting_requests: false in its public profile (association(slug)); POST /v1/enroll and POST /v1/me/membership answer 403 not_available. Someone with an invitation joins from the link they receive by mail;
• sandboxes stay open: test clients work as always.

Check aps.accepting_requests before showing an enrolment form — for the beta as for everything else; <vimine-events> and <vimine-enroll> already do.

Limits

• Per IP address: 60 requests/minute on the sensitive endpoints (card verification, fiscal code, token), 120/minute on the rest; RateLimit-* and Retry-After in the responses.
• POST /v1/me/membership accepts Idempotency-Key: the same key within 24 hours returns the same response (the SDK generates one per call).
• Authenticated responses are Cache-Control: no-store.
• Every response carries a request_id: quote it when you report a problem.