Authentication and authorization

Authentication

GipoNext APIs always require an authenticated user context. The Client Credentials (machine-to-machine) flow is not supported: every token must be associated with a person who has logged in interactively.

Supported flows

Flow	When to use
Authorization Code	Web apps with backend (PHP, .NET, Java, Python, Node.js) and native apps (desktop, mobile) that can open a browser
Device Code	Devices without browser, CLI, batch tools, or server environments without a UI

In both cases, the user logs in on account.gipo.it, authorizes your app, and the system issues an access token you use to call the APIs.

For technical implementation details (parameters, endpoints, sequence diagrams, token and refresh handling), see OAuth flows and tokens.

Authorization (OAuth scopes)

Scopes define which resources your application can access via GipoNext APIs. They work as a declarative permission system: your app declares what it needs, the user decides what to grant.

How they work

The scope lifecycle has three steps:

1. Registration — When you register your application on account.gipo.it, you declare the list of scopes you want access to. This list represents the maximum set of features your app can use (see Register your application).

2. User consent — When a user logs in via your application, they see a consent screen with the requested permissions. The user can accept or refuse each scope. If the user does not grant a scope, your app cannot use the corresponding features for that session.

3. Token usage — The access token you receive contains only the scopes actually granted by the user. Each API call is limited to those scopes: if you try to use an endpoint not covered, you will receive a 403 Forbidden error.

Handling partial consent

Your application must handle the case where the user does not grant all requested scopes. After obtaining the access token, compare the scopes in the response with those you need:

• Disable features not covered by the granted scopes, showing a clear message to the user.
• Do not block the entire application if a non-essential scope is missing.
• If needed, guide the user to grant missing permissions by starting a new authorization flow with the additional scopes.

💡 Best practice: incremental scopes

Request scopes when needed, not all upfront.

For example, request giponext.invoices only when the user accesses the invoicing section of your app.

Users tend to accept permissions more readily when requested in context.

Available scopes

The table lists all scopes you can request when registering your application.

Scope	Functionality
openid	Base OpenID Connect flow (required for all clients)
offline_access	Refresh token issuance for renewing access without new login
giponext.patients	Patients — read and write demographics
giponext.agenda	Agendas, availabilities, and appointments — read and manage calendar
giponext.treatments	Treatments and price lists — read catalog and prices
giponext.episodes	Clinical episodes — read and write patient pathways
giponext.medicalreports	Medical reports — read and write clinical documentation
giponext.invoices	Invoicing — read and write sales documents

For the full map between scopes and available API resources, see Entities and operations.

Modifying scopes after registration

Changing the scopes associated with an application is not available as self-service. If you need to add or remove scopes, contact integration support by writing to support specifying:

• the client_id of your application;
• the scopes to add or remove;
• the reason for the change.

Next steps

• OAuth flows and tokens — technical implementation of OAuth flows
• Register your application — how to obtain client_id and configure scopes
• Entities and operations — resource map, operations, and required scopes per endpoint