Această pagină se adresează dezvoltatorilor care construiesc un plugin sau o aplicație ce se conectează la contul NewsMAN al unui client. În loc să îi cereți clientului să caute și să copieze o cheie API, îl trimiteți la NewsMAN, el aprobă aplicația dumneavoastră, iar dumneavoastră primiți o cheie API pentru contul lui.
Procesul are trei pași: trimiteți utilizatorul la pagina de autorizare, primiți un cod de autorizare, schimbați codul pentru o cheie API. Sunt implicate trei adrese, toate pe această instanță:
https://newsman.app/admin/oauth/authorize - unde trimiteți clientulhttps://newsman.app/admin/oauth/token - unde schimbați codul pentru o cheiehttps://newsman.app/admin/oauth/revoke - unde returnați o cheieContactați NewsMAN înainte de a construi ceva. Aplicația dumneavoastră este înregistrată manual, iar dumneavoastră primiți un client_id și un client_secret care îi aparțin doar ei. Nu există înregistrare automată, iar niciuna dintre cele două valori nu poate fi generată de dumneavoastră: o cheie API NewsMAN nu este un client secret și nu poate fi folosită ca atare.
Spuneți-ne, în același timp:
Dacă doriți să oferiți și crearea rapidă a contului - opțiunea care permite unui client ce nu are încă un cont NewsMAN să își creeze unul chiar în pasul de autorizare, cu datele deja completate - cereți acest lucru tot atunci. Are nevoie de o semnătură calculată din client_id-ul dumneavoastră și din datele clientului, iar atât secretul folosit, cât și metoda de calcul vă sunt comunicate direct. Niciunul dintre ele nu este publicat aici.
redirect_uri este adresa la care NewsMAN trimite clientul după ce a aprobat, iar ea se stabilește la înregistrarea aplicației. Sunt două moduri de a o înregistra, iar cel care vi se potrivește depinde de locul în care rulează aplicația dumneavoastră.
Dacă aplicația rulează într-un singur loc - serviciul dumneavoastră, o singură adresă - dați-ne acea adresă. Ea este verificată exact: redirect_uri pe care îl trimiteți la fiecare cerere de autorizare trebuie să fie acel șir, caracter cu caracter. Se mai poate înregistra o a doua adresă alături de ea, dacă aveți nevoie, pentru un mediu de test sau pentru un al doilea produs.
Dacă aplicația dumneavoastră este un plugin pe care clienții îl instalează pe propriile lor site-uri, fiecare instalare are adresa ei de retur și nu le putem enumera dinainte. Spuneți-ne acest lucru la înregistrare, iar aplicația dumneavoastră va putea trimite de fiecare dată altă adresă de retur. În acest caz ecranul de aprobare îi arată clientului adresa exactă la care va fi trimis codul - gazda întreagă, deci shop.example.com, nu example.com - deci spuneți-i la ce să se aștepte.
Indiferent de tipul înregistrat, adresa de retur trebuie să fie o adresă http sau https absolută, cu nume de domeniu. O adresă scrisă ca IP este refuzată, la fel și una care poartă credențiale înaintea gazdei sau care conține backslash, spațiu ori caractere de control: browserul și parserul nostru nu le citesc la fel, deci nu putem garanta că i se arată clientului unde ajunge de fapt. Pentru un domeniu internaționalizat, înregistrați forma ASCII - xn--mller-kva.example, nu müller.example - pentru că aceea este forma pe care i-o putem arăta clientului neschimbată.
În oricare dintre situații, adresa de retur cu care începeți procesul este cea pe care trebuie să o trimiteți din nou când schimbați codul, iar atunci este verificată. Adresa de retur poate avea propriul query string, pe care îl păstrăm, dar el nu are voie să conțină deja code, state, error sau error_description: acestea sunt numele pe care le adăugăm noi, iar un nume care ajunge de două ori este citit de unele biblioteci cu prima valoare, de altele cu ultima. Dacă adresa dumneavoastră de retur se termină cu un fragment - tot ce urmează după # - parametrii răspunsului sunt adăugați înaintea lui, deci citiți code și state din query string, nu din fragment.
Redirecționați browserul clientului către https://newsman.app/admin/oauth/authorize, cu următorii parametri în query:
response_type - întotdeauna code, singurul tip de răspuns acceptat.client_id - id-ul emis pentru aplicația dumneavoastră.scope - întotdeauna api. Este singurul scope care există, nu este un selector de permisiuni și nu restrânge ce poate face cheia rezultată.redirect_uri - adresa dumneavoastră de retur, codificată URL.state - opțional, dar recomandat: orice valoare generați dumneavoastră, returnată neschimbată. Folosiți-o pentru a lega răspunsul de cerere și ca protecție împotriva atacurilor cross-site request forgery.Adresa completă:
https://newsman.app/admin/oauth/authorize?response_type=code&client_id=yourplugin&scope=api&redirect_uri=https%3A%2F%2Fyourplugin.example%2Fnewsman%2Fcallback&state=6f1a9c2eDacă clientul nu este autentificat, NewsMAN îi cere mai întâi să se autentifice și apoi îl aduce automat înapoi la ecranul de aprobare. Ecranul îi arată numele aplicației dumneavoastră și, atunci când adresele de retur sunt per instalare, site-ul pentru care se face autorizarea.
Erorile din cererea în sine nu ajung deloc la adresa dumneavoastră de retur. Dacă client_id este necunoscut, redirect_uri nu corespunde înregistrării dumneavoastră sau response_type ori scope nu au valorile de mai sus, clientului i se arată un HTTP 400 cu un corp JSON, în loc să fie redirecționat - nu există o adresă verificată către care să fie trimis. Dacă vedeți acest lucru în browser, înseamnă că adresa de autorizare și înregistrarea nu coincid.
Când clientul aprobă, NewsMAN redirecționează browserul înapoi către redirect_uri, cu codul de autorizare adăugat și, dacă ați trimis una, cu valoarea state:
https://yourplugin.example/newsman/callback?code=01****************************84&state=6f1a9c2eCând clientul nu aprobă sau nu poate, sunteți trimis înapoi la aceeași adresă cu o eroare în locul codului. Sunt trei, și ar trebui să le tratați pe toate - prima este un rezultat normal, nu o eroare:
error=access_denied&error_description=end-user+denied+authorization - clientul a apăsat butonul de refuz.error=access_denied&error_description=end-user+denied+authorization+for+list - clientul nu a ales o listă pe un ecran care cerea acest lucru.error=missing_lists&error_description=no-lists+found+authorization - contul nu are nicio listă, deci nu există la ce să vă dea acces. Spuneți-i clientului să creeze o listă în NewsMAN și să reia procesul.Valoarea dumneavoastră state revine și pe aceste redirecționări, așa că verificarea pe care o faceți la un retur reușit se aplică și unui refuz.
Trimiteți o cerere POST către https://newsman.app/admin/oauth/token. Parametrii sunt codificați ca formular:
grant_type - întotdeauna authorization_code.code - codul primit la pasul 2.client_id - id-ul emis pentru aplicația dumneavoastră.client_secret - secretul emis împreună cu el. Trimiteți-l de pe serverul dumneavoastră, niciodată din browserul clientului.redirect_uri - aceeași valoare trimisă la pasul 1.curl -X POST 'https://newsman.app/admin/oauth/token' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=01****************************84' \
--data-urlencode 'client_id=yourplugin' \
--data-urlencode 'client_secret=7c****************************e9' \
--data-urlencode 'redirect_uri=https://yourplugin.example/newsman/callback'Un schimb reușit returnează HTTP 200 și un corp JSON:
{
"access_token": "9f****************************c4",
"token_type": "bearer",
"scope": "api",
"expires_in": 1804204800,
"user_id": 58000032,
"username": "client@example.com",
"firstname": "John",
"lastname": "Doe",
"lists": [5130, 5131],
"api_endpoint": "https://api.newsman.app/v2/",
"lists_data": {
"5130": {"list_id": "5130", "name": "Newsletter", "type": "newsletter"},
"5131": {"list_id": "5131", "name": "SMS alerts", "type": "sms"}
}
}Câmpurile care contează sunt access_token, user_id, lists și api_endpoint. Sunt descrise în Ce aveți acum. expires_in nu este printre ele - citiți Cât timp este valabilă cheia înainte de a construi ceva pe baza lui.
Dacă schimbul eșuează, primiți HTTP 400 și un corp JSON care numește eroarea:
{
"error": "invalid_grant",
"error_description": "Authorization code doesn't exist or is invalid for the client"
}Valorile error sunt:
invalid_request - grant_type nu a fost trimis.unsupported_grant_type - grant_type a fost altceva decât authorization_code.invalid_grant - codul este necunoscut.invalid_client - client_secret lipsește sau este greșit, ori codul a fost emis pentru un alt client_id.redirect_uri_mismatch - redirect_uri lipsește sau nu este cel pentru care a fost emis codul.access_token este cheia API NewsMAN a clientului, iar user_id este contul căruia îi aparține. Împreună autentifică fiecare apel API ulterior, așa că păstrați-le pe amândouă.
api_endpoint este adresa de bază a API-ului pentru acel cont. Este derivată din cont, nu din adresa pe care tocmai ați apelat-o, deci poate să difere de adresa din URL-ul de autorizare. Păstrați valoarea primită, în loc să presupuneți una.
Cum autentificați un apel cu această cheie și ce metode există sunt documentate în referința REST API, pe care o puteți deschide și din comutatorul din partea de sus a paginii.
lists conține id-urile listelor cu care cheia dumneavoastră poate lucra: toate listele la care are acces persoana care a aprobat aplicația. Un apel care numește orice altă listă este respins. Dacă aprobarea a venit dintr-un subcont, este vorba de listele acelui subcont, nu de toate listele contului.
lists_data le descrie - id-ul, numele pe care clientul l-a dat listei și tipul ei, care este newsletter pentru o listă de email sau sms pentru o listă SMS. Folosiți-l ca să îi arătați clientului la ce liste sunteți conectat, fără un apel API suplimentar.
lists_data este prezent doar când accesul acoperă cel puțin o listă, deci citiți-l defensiv. lists este câmpul pe care să vă bazați.
Setul este fixat în momentul aprobării. O listă creată ulterior nu se adaugă de la sine la o cheie existentă: clientul o poate adăuga editând cheia din Cont și apoi API, sau îl puteți trece din nou prin flux pentru o cheie nouă. Același ecran îi permite să restrângă cheia - la anumite liste, la anumite adrese IP sau doar la import și abonare - așa că un apel poate începe să eșueze fără ca cheia să fi fost revocată.
Cheia nu expiră. Rămâne valabilă până când este revocată.
Ignorați expires_in. Este prezent în răspuns pentru compatibilitate, dar nimic nu îl impune, iar valoarea lui nu este o durată, așa că un timer de expirare construit pe el va da un rezultat greșit.
Nu există refresh token și nu există pas de refresh, pentru că nu este nimic de reîmprospătat. Dacă o cheie nu mai este acceptată deloc, înseamnă că a fost revocată, iar modul de a obține una nouă este să reluați fluxul de autorizare.
Acesta este scenariul de eșec pentru care trebuie să proiectați. O cheie nu expiră la un moment pe care îl puteți anticipa și pentru care vă puteți pregăti - se oprește în clipa în care un client deconectează aplicația dumneavoastră, iar dumneavoastră aflați la următorul apel pe care îl faceți. Tratați o eroare de autentificare drept "reconectați acest cont", nu drept o eroare de reîncercat.
Oricare dintre părți poate revoca:
https://newsman.app/admin/oauth/revoke ca parametru token. Faceți acest lucru când un client dezinstalează plugin-ul dumneavoastră, ca să nu lăsați în urmă o cheie funcțională.