Autenticazione

L'API di Rently usa OAuth2 con token Bearer. Il flusso è semplice: richiedi un token con le tue credenziali, lo salvi e lo invii nell'header Authorization di ogni richiesta. Questa guida spiega come ottenere il token, come usarlo, la sua scadenza e la relazione tra il token e il tuo tenant.

Il modello in una frase

1. Fai POST /auth/token con le tue credenziali e ricevi un access_token.
2. Invii quel token nell'header Authorization: Bearer {token} in ogni chiamata a /api/....
3. Il token resta legato al tuo tenant (il tuo host) e scade dopo un giorno (expires_in ≈ 86399 secondi).

Credenziali

Il tuo client_id è il tuo utente di Rently e il tuo client_secret è la tua chiave. Se non hai ancora un utente abilitato per l'API, contatta il tuo amministratore di Rently.

Ottenere il token

L'endpoint del token risiede sull'host del tuo tenant e si chiama con grant_type=client_credentials. Il corpo viene inviato come application/x-www-form-urlencoded.

curl -X POST https://{tenant}.rently.com.ar/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id={username}" \
  -d "client_secret={password}"

Provalo dal vivo

Puoi provare questo endpoint in modo interattivo —compila client_id, client_secret e l'host del tuo tenant, e invia la richiesta— nella reference: Ottenere un token di accesso.

L'endpoint del token risiede sull'host del tuo tenant

https://{tenant}.rently.com.ar è usato come esempio. In produzione devi puntare sia l'endpoint del token sia le chiamate di business all'host del tuo tenant. L'host identifica il tenant: il token che emette resta legato a quel tenant. Usare il token contro un host di un altro tenant fa fallire la validazione (vedi Ruolo del tenant).

Parametri del corpo

Campo	Valore	Descrizione
grant_type	client_credentials	Valore fisso. È il flusso usato dai client dell'API.
client_id	il tuo utente	Utente di Rently abilitato per l'API.
client_secret	la tua chiave	Chiave dell'utente.

Risposta

Se le credenziali sono valide, ricevi un JSON con il token:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiAi...",
  "token_type": "bearer",
  "expires_in": 86399
}

Campo	Tipo	Descrizione
access_token	string	Il token da inviare in ogni richiesta.
token_type	string	Schema di autorizzazione. Sempre bearer.
expires_in	number	Secondi fino alla scadenza (≈ 1 giorno).

suggerimento

Salva l'access_token e riutilizzalo in tutte le tue chiamate finché non scade. Non richiedere un token nuovo a ogni richiesta: il token è valido per tutta la giornata.

Usare il Bearer token

In ogni chiamata all'API invii il token nell'header Authorization, con lo schema Bearer:

Authorization: Bearer {access_token}

Esempio di una richiesta autenticata contro un endpoint reale dell'API. GET /api/branchoffices elenca le filiali attive:

curl -X GET "https://{tenant}.rently.com.ar/api/branchoffices?language=es-AR" \
  -H "Authorization: Bearer {access_token}"

Lingua della risposta

Il query param ?language= controlla la lingua della risposta (per esempio ?language=es-AR). Se lo ometti, si usa la lingua predefinita del tuo tenant. Accetta sia la cultura completa (es-AR) sia il codice di due lettere (es).

Tutti gli endpoint di business (/api/...) richiedono questo header. Puoi vedere il dettaglio di ogni operazione, i suoi parametri e le sue risposte nella API Reference →.

Scadenza e rinnovo

Il token scade circa un giorno dopo l'emissione (expires_in ≈ 86399 secondi). Non esiste un meccanismo di refresh token: quando il token scade, semplicemente ne richiedi uno nuovo ripetendo il POST /auth/token con le tue credenziali.

Se invii un token scaduto, assente o non valido, l'API risponde 401 Unauthorized con un header WWW-Authenticate che punta all'endpoint del token del tuo tenant:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri=https://{tenant-host}/auth/token, resource_id=https://{tenant-host}/api

Strategia consigliata

Salva la data/ora in cui hai richiesto il token e rinnovalo in modo proattivo prima che si raggiunga expires_in. In alternativa, in modo reattivo, in presenza di un 401 richiedi nuovamente il token e riprova la richiesta.

Ruolo del tenant

Il tenant si risolve a partire dall'host dell'URL. Quando ottieni un token, il tenant corrispondente a quell'host resta incorporato nel token come claim.

In ogni chiamata di business, l'API valida due cose:

1. Che il token sia valido e non scaduto.
2. Che il tenant del token coincida con il tenant dell'host della richiesta.

Un token = un tenant

Un token emesso per un tenant non funziona per un altro. Se riutilizzi un token contro l'host di un tenant diverso, la validazione fallisce con 401. Richiedi sempre il token sullo stesso host dove farai le chiamate di business.

Inoltre, emettere il token e autorizzare ogni endpoint sono livelli separati: l'utente deve essere abilitato a usare l'API, e poi ogni operazione applica i propri permessi. Se il tuo utente non ha il permesso su un endpoint, la richiesta può essere rifiutata anche se il token è valido.

Riepilogo

• Token: POST /auth/token con grant_type=client_credentials, client_id (utente) e client_secret (chiave), come application/x-www-form-urlencoded, sull'host del tuo tenant.
• Risposta: access_token, token_type: "bearer", expires_in (≈ 1 giorno).
• Uso: header Authorization: Bearer {access_token} in ogni chiamata a /api/....
• Scadenza: ≈ 1 giorno, senza refresh token; richiedi un token nuovo quando scade.
• Tenant: il token resta legato all'host/tenant dove l'hai richiesto; non riutilizzarlo contro un altro tenant.

Con il token in mano, continua a esplorare gli endpoint nella API Reference →.