# Register a client

> How a director registers an integration from the Developers console, which kind to pick, what has to be registered exactly.

URL: https://developers.vimine.network/en/start/register-a-client/

Every integration is a **client** registered from the **Developers** console of the Vimine app. The console
is reserved to the association's board: if you are not on it, ask a director to register the client for you
and hand you the credentials.

Without an association — an agency, someone building a plugin, someone trying the API — ask the platform for a
**developer invitation**: you get a [sandbox](https://developers.vimine.network/en/guides/sandbox/) of your own, a test association with synthetic members,
and register your test clients there yourself, accepting the developer terms. Production clients stay with the
association you work for.

## Client kinds

| Kind | For | Credentials | Notes |
|---|---|---|---|
| **Website** (public) | pages in the browser | `client_id` only | PKCE required; exact `https` redirect URIs |
| **Native app** | mobile or desktop apps | `client_id` only | as above; loopback redirects (`http://127.0.0.1:{port}/…`) or a custom scheme |
| **Server** (confidential) | a backend of the association | `client_id` + `client_secret` | the secret is shown once; never in a browser |

Public and native clients do **Sign in with Vimine** and call the API with the member's token.
Confidential clients can additionally authenticate on their own (`client_credentials`) for the "client"
permissions, such as card statuses.

## Environments

| Environment | Where it lives | When it is active |
|---|---|---|
| **Test** | in the association's [sandbox](https://developers.vimine.network/en/guides/sandbox/) (created on demand) | **immediately** |
| **Production** | in the real association | after activation by Vimine: you receive an e-mail |

Test clients issue tokens with `mode: "test"` and cannot touch the real association. Their confidential
credentials start with `vms_test_`.

## What to register

1. **Name** — what the member will see on the consent page ("*Name* wants to access your profile…").
2. **Kind** and **environment**.
3. **Redirect URIs** — the pages Vimine may send the browser back to after sign-in. Matching is **exact**
   (scheme, host, port, path): register every callback page you will use.
4. **Allowed origins** — the origins (`https://www.example.org`) your pages call the API from in the browser.
   They are used for CORS and as allowed destinations after sign-out (`post_logout_redirect_uri`).
5. **Permissions** — the scopes the integration may ask for. Ask only for what you need: the member sees them
   all. A public or native client may only hold member permissions; "client" permissions require a confidential
   client. Table in [Permissions, errors and limits](https://developers.vimine.network/en/guides/scopes-and-errors/).

On creation you get the `client_id` (`vmc_…`) and, for confidential clients, the `client_secret` (`vms_…`),
shown **once only**. For test clients the console also shows the sandbox's synthetic members and their
password.

## Lifecycle

- **Rotate secret** — the new secret is shown once; **the previous one keeps working for 24 hours**, so you
  can update your systems without downtime.
- **Suspend** — the client's tokens stop working until you re-enable it. Re-enabling is in the board's hands.
- **Revoke** — final: every session of the client ends immediately and members no longer see it among their
  connected apps.
- Members can withdraw consent at any time from **Connected apps** in their account: that client's sessions
  for that member end.

:::tip[Local development]
A **test** client may have `http://localhost:…` redirect URIs and origins: that is the normal way to develop.
In production only `https` (loopback aside, for native apps).
:::