Questa guida ti accompagna passo-passo nell'ottenere le credenziali necessarie per autenticare le tue richieste all'API Italianonprofit.
Hai due opzioni per autenticare le tue richieste:
Quando usarlo:
Caratteristiche:
Quando usarlo:
Caratteristiche:
Invia una richiesta POST all'endpoint di login con le tue credenziali:
curl -X POST https://nitro.italianonprofit.it/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "tuo@email.com",
"password": "tua-password"
}'
La risposta contiene i token che devi salvare:
{
"status": "success",
"data": {
"accessToken": "v4.public.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ...",
"refreshToken": "v4.public.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ...",
"expiresIn": 3600,
"user": {
"id": 123,
"email": "tuo@email.com",
"name": "Nome Utente",
"role": "user"
}
}
}
Cosa salvare:
accessToken: Usalo per autenticare le richieste APIrefreshToken: Usalo per ottenere nuovi access token quando scadonoIncludi l'access token nell'header Authorization:
curl -X POST https://nitro.italianonprofit.it/api/v1/organizations/search \
-H "Authorization: Bearer v4.public.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ..." \
-H "Content-Type: application/json" \
-d '{
"index": "organization-serp*",
"body": {
"query": {
"match": {
"name": "associazione"
}
}
}
}'
async function loginAndGetToken(email, password) {
const response = await fetch("https://nitro.italianonprofit.it/api/v1/auth/login", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({ email, password }),
});
const data = await response.json();
if (data.status === "success") {
// Salva i token
localStorage.setItem("accessToken", data.data.accessToken);
localStorage.setItem("refreshToken", data.data.refreshToken);
return {
accessToken: data.data.accessToken,
refreshToken: data.data.refreshToken,
};
} else {
throw new Error(data.error.message);
}
}
// Usa il token per fare richieste
async function searchOrganizations(query) {
const accessToken = localStorage.getItem("accessToken");
const response = await fetch("https://nitro.italianonprofit.it/api/v1/organizations/search", {
method: "POST",
headers: {
Authorization: `Bearer ${accessToken}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
index: "organization-serp*",
body: {
query: {
match: {
name: query,
},
},
},
}),
});
return await response.json();
}
Prima di creare un'API Key, devi essere autenticato con un token PASETO. Segui i passi del Metodo 1 per ottenere un token.
Invia una richiesta POST per creare una nuova API Key:
curl -X POST https://nitro.italianonprofit.it/api/v1/api-keys \
-H "Authorization: Bearer <tuo-access-token>" \
-H "Content-Type: application/json" \
-d '{
"name": "My Integration",
"scopes": ["organizations:read"]
}'
Parametri:
name (obbligatorio): Nome descrittivo per identificare l'API Keyscopes (opzionale): Array di permessi. Se non specificato, viene assegnato organizations:read di defaultexpiresIn (opzionale): Durata in giorni (default: 365)IMPORTANTE: L'API Key completa sarà visibile solo in questa risposta!
{
"status": "success",
"data": {
"id": "uuid-della-chiave",
"name": "My Integration",
"key": "npf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
"prefix": "npf_a1b2c3d4",
"scopes": ["organizations:read"],
"expiresAt": "2024-12-31T23:59:59.999Z",
"createdAt": "2024-01-01T00:00:00.000Z"
},
"message": "API Key creata con successo. Salva la chiave in un posto sicuro, non sarà più visibile dopo."
}
Salva il campo key in un posto sicuro (variabile d'ambiente, secret manager, ecc.). Non sarà più visibile dopo questa risposta.
Puoi usare l'API Key in tre modi:
Metodo 1: Header Authorization Bearer
curl -X POST https://nitro.italianonprofit.it/api/v1/organizations/search \
-H "Authorization: Bearer npf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" \
-H "Content-Type: application/json" \
-d '{...}'
Metodo 2: Header X-API-Key
curl -X POST https://nitro.italianonprofit.it/api/v1/organizations/search \
-H "X-API-Key: npf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" \
-H "Content-Type: application/json" \
-d '{...}'
Metodo 3: Query Parameter (meno sicuro, non consigliato)
curl -X POST "https://nitro.italianonprofit.it/api/v1/organizations/search?api_key=npf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" \
-H "Content-Type: application/json" \
-d '{...}'
import requests
import os
# Passo 1: Login per ottenere token temporaneo
def login(email, password):
response = requests.post(
'https://nitro.italianonprofit.it/api/v1/auth/login',
json={'email': email, 'password': password}
)
data = response.json()
return data['data']['accessToken']
# Passo 2: Crea API Key
def create_api_key(access_token, name, scopes=None):
payload = {'name': name}
if scopes:
payload['scopes'] = scopes
response = requests.post(
'https://nitro.italianonprofit.it/api/v1/api-keys',
headers={'Authorization': f'Bearer {access_token}'},
json=payload
)
data = response.json()
if data['status'] == 'success':
api_key = data['data']['key']
# Salva in variabile d'ambiente o secret manager
os.environ['ITALIANONPROFIT_API_KEY'] = api_key
return api_key
else:
raise Exception(data['error']['message'])
# Passo 3: Usa API Key per fare richieste
def search_organizations(query):
api_key = os.environ.get('ITALIANONPROFIT_API_KEY')
response = requests.post(
'https://nitro.italianonprofit.it/api/v1/organizations/search',
headers={
'Authorization': f'Bearer {api_key}',
'Content-Type': 'application/json'
},
json={
'index': 'organization-serp*',
'body': {
'query': {
'match': {
'name': query
}
}
}
}
)
return response.json()
# Esempio di utilizzo
if __name__ == '__main__':
# Login una volta per creare API Key
token = login('tuo@email.com', 'tua-password')
api_key = create_api_key(token, 'My Python Integration', ['organizations:read'])
# Usa API Key per tutte le richieste successive
results = search_organizations('associazione')
print(results)
{
"status": "error",
"error": {
"code": "AUTHENTICATION_REQUIRED",
"message": "Email o password non valide"
}
}
Soluzione: Verifica che email e password siano corrette.
{
"status": "error",
"error": {
"code": "TOKEN_EXPIRED",
"message": "Token non valido o scaduto"
}
}
Soluzione: Usa il refresh token per ottenere un nuovo access token. Vedi la guida per gestire i token.
{
"status": "error",
"error": {
"code": "AUTHENTICATION_REQUIRED",
"message": "API Key non valida"
}
}
Soluzione: Verifica che l'API Key sia corretta e non sia stata revocata.