Tenant

A tenant represents a medical centre within GipoNext. Each clinic, practice, or polyclinic that uses GipoNext is a separate tenant, identified by a unique tenantId.

The tenantId is the fundamental discriminator for all API calls: it separates one medical centre's data from another's. Patients, appointments, invoices, reports, and every other resource always belong to a specific tenant and are not visible or accessible to others.

In practice, almost all API endpoints follow the pattern:

/v2/tenants/{tenantId}/...

The tenantId appears in the path because every operation occurs in the context of a single medical centre.

How to obtain tenantId

Each GipoNext user belongs to one tenant only, set when the account was created. You cannot change tenant during a session or access tenants other than your own.

After OAuth login, the first step is to call the UserInfo endpoint to discover which tenant the authenticated user is linked to:

GET https://api.giponext.it/v2/userinfo
Authorization: Bearer <access_token>

{
  "sub": "user-id",
  "name": "Mario Rossi",
  "tenants": [
    { "id": "tenant-abc123", "name": "Example Clinic" }
  ]
}

The tenants field contains the user's tenant. Use the id value as {tenantId} in all subsequent calls.

No tenant filter on the application

Your OAuth application does not filter users in advance by tenant. This means virtually any active GipoNext user can authenticate via your app, regardless of which clinic they belong to.

In practice: if your integration is designed for a single medical centre, nothing prevents a user from another clinic from logging in. The OAuth system only verifies that the user is valid and your app is approved; it does not check which clinic they belong to.

Tenant filtering is the integrator's responsibility

If your application logic requires operating only with one or more specific tenants, you must implement the check after login:

1. Call /v2/userinfo to obtain the user's tenantId.
2. Compare the tenantId with the list of tenants authorized for your application.
3. If the tenant is not among those allowed, deny access and show a clear message to the user (e.g. "This application is reserved for Clinic XYZ").

⚠️ Note

Do not rely on "only the right users know the credentials". Tenant security must be implemented explicitly in your code.

Sandbox environment

For developing and testing your integration you do not need access to the production tenant. In fact, it is good practice not to access it during development: the production tenant contains real health data subject to privacy regulations.

Gipo provides each integrator with a sandbox tenant: an isolated, initially empty environment where you can:

• create fictitious patients, appointments, invoices, and reports;
• test all flows (create, read, update, delete) without risk;
• validate your app's behaviour end-to-end before going to production;
• show the client a working prototype without involving real data.

The sandbox tenant is completely separate from production tenants: nothing you do in sandbox affects medical centre data.

💡 Request your sandbox tenant

If you do not have one yet, request activation by writing to support. You will receive it ready to use with access credentials.

When to access the production tenant

Access to the medical centre's real data happens only when development is complete, on explicit request from the medical centre. The procedure is described in Register your application — Production data access.

Next steps

• Entities and operations — resources available per tenant and required scopes
• Authentication and authorization — how OAuth login works
• OAuth flows and tokens — why two identities are needed
• Register your application — OAuth provisioning and production data access