# Vimine for developers

> Vimine is the membership platform for Italian associations (APS) and Third Sector organisations. For developers working for an association: Sign in with Vimine (OAuth 2.1 + PKCE), the member API, server integrations, card verification, the public profile and the enrolment form — with the JavaScript SDK `@vimine/sdk`, the OpenAPI 3.1 reference and these guides.

Rules for code assistants:

- The `client_secret` (`vms_…`) never goes into code that runs in a browser or an app: websites and apps are public clients, using authorization code + PKCE (S256) and a `state` compared on return.
- Members sign in only on Vimine's page (`https://app.vimine.network/authorize`), reached by a redirect: never a credentials form on your site, never in an iframe.
- The secret lives only on a server: `client_credentials` for the association's own systems; HTTP Basic directly only where the reference allows it, never from a browser.
- Start with a test client in the association's sandbox (synthetic members, active at once); a production client works after Vimine activates it.
- Use the SDK (`@vimine/sdk`, `@vimine/sdk/react`, `@vimine/sdk/server`) instead of rewriting the OAuth flow; tokens stay in `sessionStorage` (per tab) unless you choose otherwise knowingly.
- Check `aps.accepting_requests` before showing an enrolment form; retry a membership request (`POST /v1/me/membership`) with the same `Idempotency-Key`, never a new one.
- Errors are `application/problem+json` (RFC 9457) with a stable `code`: branch on the `code`, not the text, and quote the `request_id` when you report a problem.
- Ask only for the scopes you need: the member sees each one on the consent page.
- Never combine data from different associations: a member's `sub` differs from one association to the next, and the developer terms forbid correlating them.

## Get started

- [Overview](https://developers.vimine.network/en/start/overview.md): What the Vimine API offers to whoever builds for an association, and the concepts to know before starting.
- [Register a client](https://developers.vimine.network/en/start/register-a-client.md): How a director registers an integration from the Developers console, which kind to pick, what has to be registered exactly.
- [Install the SDK](https://developers.vimine.network/en/start/install.md): The @vimine/sdk package, its three entry points, the requirements.

## Guides

- [Sign in with Vimine](https://developers.vimine.network/en/guides/sign-in.md): The OAuth 2.1 + PKCE flow from the click to the callback, the session, API calls and sign-out, with and without the SDK.
- [Sandbox and test clients](https://developers.vimine.network/en/guides/sandbox.md): The twin association with synthetic members in every state, test clients and the reset.
- [Server integrations](https://developers.vimine.network/en/guides/server.md): Confidential clients for the association's own systems, client_credentials, card status, secret rotation.
- [Admission and activation](https://developers.vimine.network/en/guides/admission.md): How an association admits its members, when the fee is paid, when the card counts at the door — and what to tell people who join from your site.
- [Members without a fiscal code](https://developers.vimine.network/en/guides/members-without-cf.md): A person is identified by a fiscal code or by their date, place and country of birth. What to send for people born abroad, how a code that disagrees is confirmed, what to show at the gate.
- [Languages](https://developers.vimine.network/en/guides/languages.md): Ask for an association's copy in another language with ?locale=, tell from locale and locales what was served, say which language to write to a person in. Never a machine translation.
- [Embed and card verification](https://developers.vimine.network/en/guides/embed-and-verify.md): The enrolment form on your site, the association's public profile and card verification online and offline.
- [Events and registrations](https://developers.vimine.network/en/guides/events.md): Publish the association's events on your site, let members register (and guests, for public events), check people in at the door with the same scanner as the cards.
- [WordPress plugin](https://developers.vimine.network/en/guides/wordpress.md): Sign in with Vimine, the member card and enrolment on the association's WordPress site — no code.
- [Permissions, errors and limits](https://developers.vimine.network/en/guides/scopes-and-errors.md): The scope table, the error format (RFC 9457) with stable codes, the rate limits.

## SDK

- [Vimine (browser)](https://developers.vimine.network/en/sdk/browser.md): Reference of the Vimine class of @vimine/sdk — sign-in, session, API calls, storage.
- [React](https://developers.vimine.network/en/sdk/react.md): VimineProvider, useVimine and SignInButton from @vimine/sdk/react.
- [Elements (low-code)](https://developers.vimine.network/en/sdk/elements.md): The <vimine-sign-in>, <vimine-card> and <vimine-enroll> custom elements — one HTML tag, no framework.
- [VimineServer](https://developers.vimine.network/en/sdk/server.md): Reference of the VimineServer class of @vimine/sdk/server for confidential clients.
- [Public API](https://developers.vimine.network/en/sdk/public.md): publicApi() — card verification, an association's public profile, fiscal code, public keys. No credentials.
- [Errors](https://developers.vimine.network/en/sdk/errors.md): VimineError — one error type for everything the API and the SDK can refuse, with a stable code.
- [Types](https://developers.vimine.network/en/sdk/types.md): The SDK's TypeScript types — the same JSON shapes as API v1, field names unchanged.

## HTTP API

- [OpenAPI 3.1 document](https://api.vimine.network/v1/openapi.json): The whole API: paths, scopes, schemas and errors.
- [OAuth discovery (RFC 8414)](https://api.vimine.network/.well-known/oauth-authorization-server): Authorization, token and revocation endpoints; supported PKCE methods and scopes.
- [Interactive console](https://developers.vimine.network/en/api/console/): Try the calls against the sandbox with a test client.

## Optional

- [Everything in one file](https://developers.vimine.network/en/llms-full.txt): Every page in this language in a single Markdown file.
- [@vimine/sdk on npm](https://www.npmjs.com/package/@vimine/sdk): The SDK: browser, React and server.
- [Italiano](https://developers.vimine.network/llms.txt): The same pages in Italiano.
- [Français](https://developers.vimine.network/fr/llms.txt): The same pages in Français.
- [Español](https://developers.vimine.network/es/llms.txt): The same pages in Español.
- [Deutsch](https://developers.vimine.network/de/llms.txt): The same pages in Deutsch.
- [Português (Brasil)](https://developers.vimine.network/pt/llms.txt): The same pages in Português (Brasil).
- [简体中文](https://developers.vimine.network/zh-hans/llms.txt): The same pages in 简体中文.
- [繁體中文](https://developers.vimine.network/zh-hant/llms.txt): The same pages in 繁體中文.