code, som därefter byts mot en OAuth access token.
OAuth access token används för att komma åt kontoresursgränssnitt; för att anropa modell-API:er används motsvarande API Key. OAuth-auktorisering skapar inte automatiskt API Key, aktiverar tjänster eller ökar saldo.
Välj integrationsmetod
Standardomdirigering kräver inte
embed=studio, embed_origin eller postMessage. Studio-komponentläget skapar auktoriseringssidan och upprätthåller meddelandebryggan via värden; tredje parter integrerar enligt komponentprotokollet i slutet av denna text och ska inte själva sammanfoga dessa två parametrar.
Slutpunkter och upptäcktsdokument
Applikationshanteringsgränssnittet kräver kontoinloggningsautentisering och är inte ett gränssnitt för anonym dynamisk registrering (DCR). MCP-tjänstens egna upptäckts-/registreringsadresser är separata ingångar från kontots OAuth-slutpunkter i denna tabell; följ dokumentationen och upptäcktsresultaten för den specifika MCP-tjänsten vid anslutning.
Upptäcktsdokumentet används för att hämta slutpunkter och protokollfunktioner. Det aktuella flödet returnerar OAuth token, inte
id_token; hantera inte detta som ett fullständigt OpenID Connect-inloggningsflöde enbart eftersom scopet openid finns.
Behörighetsomfång: använd aktuella scope-namn
scope är ett mellanslagsseparerat, skiftlägeskänsligt behörighetsnamn. Nya applikationer använder specifika behörigheter som profile:read, email:read, phone:read och så vidare.
Var du hämtar behörigheter som kan begäras
Efter inloggning returnerar OAuth-applikationslistans gränssnittGET /api/v1/oauth2/applications/ available_scopes; behörighetsväljaren på applikationshanteringssidan använder samma katalog. Detta är de valbara omfång som vanliga självbetjäningsapplikationer ska använda.
Discoverys scopes_supported innehåller alla behörighetsnamn som identifieras av plattformen, men innebär inte att din applikation kan begära vart och ett av dem. Faktisk auktorisering kontrollerar samtidigt:
- om behörigheten får delegeras till denna applikationstyp;
- om behörigheten har registrerats inom de tillåtna omfången för denna OAuth-applikation;
- om den aktuella användaren har den begärda behörigheten.
invalid_scope. Vid utbyte och förnyelse av auktoriseringskod kontrolleras behörigheter också på nytt; behörigheter kompletteras eller höjs inte automatiskt.
Valbara behörigheter för vanliga självbetjäningsapplikationer
Följande är den aktuella katalogen (2026-10-09); användavailable_scopes vid integrering.
Till exempel används
profile:read för att endast läsa profil; lägg till email:read om e-post behövs; använd profile:read credentials:read för att läsa befintliga API Key. Begär endast credentials:write när du verkligen behöver skapa eller ändra Key, och lägg till offline_access när förnyelse behövs.
Vissa behörigheter är endast avsedda för betrodda applikationer godkända av plattformen, exempelvis sites:read, sites:write, platform-tokens:read; andra behörigheter är inte öppna för vanliga OAuth-applikationer från tredje part. Klienttypen public/confidential beskriver huruvida en secret kan förvaras säkert och har inget samband med om applikationen är betrodd. Självbetjäningsskapade applikationer kan inte själva aktivera betrodda behörigheter.
account är en behörighetsväljare för konton som används av det angivna officiella MCP för kontohantering, och är inte scopet ”alla behörigheter” för tredjepartsapplikationer; det kan inte användas tillsammans med andra scope. Tredje parter ska uttryckligen lista de specifika behörigheter som behövs.
Migrera från äldre dokumentation
Äldre namn accepteras inte som kompatibilitetsalias. Uppdatera samtidigt scopes som registrerats för OAuth-applikationen, auktoriserings-URL:en och dina egna behörighetskontroller; ändring av applikationskonfigurationen ger inte redan utfärdade token fler behörigheter, användaren måste auktorisera på nytt.
Steg 1: Registrera OAuth-applikationen
Öppna OAuth-applikationshantering, skapa en applikation och fyll i:- Namn, beskrivning, applikationslogo: visas på applikationssidan på auktoriseringssidan.
- Klienttyp: välj Public för ren frontend, mobil- eller skrivbordsklienter; välj Confidential för tjänster som kan förvara secret på backend.
- Återanropsadress: använd HTTPS i produktionsmiljön och registrera den fullständiga URL där applikationen faktiskt hanterar återanropet.
- Behörigheter: välj de scopes som faktiskt behövs från katalogen som sidan tillhandahåller.
client_id. Confidential-klienter ska förvara client_secret på serversidan och får inte placera det i HTML, frontend-byggvariabler eller URL:er. Public-klienter använder inte secret för att hämta token; även om registreringssvaret innehåller detta fält får det inte behandlas som en uppgift som klienten kan hålla hemlig.
redirect_uri måste vara exakt identisk vid registrering, auktorisering och token-utbyte, inklusive sökväg, avslutande snedstreck och frågeparametrar. Varje konto kan skapa högst 20 applikationer. Secret visas endast vid skapande/rotation; efter rotation kan det gamla secret inte längre användas för utbyten som kräver klientautentisering.
Steg 2: Knappen initierar auktorisering
Vid varje klick på anslutning, generera nya slumpmässigastate och code_verifier, beräkna:
state, verifier och återanropsadress i applikationens egen session, och öppna sedan auktoriseringssidan med URL-kodade parametrar:
plain får Public-klienter inte använda det. Confidential-klienter rekommenderas också att använda S256; om PKCE användes när auktoriseringen initierades måste motsvarande verifier skickas vid utbytet.
Efter att användaren godkänt återgår den till redirect_uri, där frågeparametrarna innehåller code och det oförändrat returnerade state. Vid avslag returneras error=access_denied, felbeskrivning och state. Verifiera först att state matchar den aktuella sessionen innan återanropet behandlas. Auktoriseringskoden är giltig i 10 minuter och kan endast lösas in en gång; initiera anslutningen på nytt efter fel och uppdatera inte upprepade gånger den gamla återanrops-URL:en.
Steg 3: Byt mot OAuth-token
Public-klienter löser in direkt från webbläsaren eller klienten; Confidential-klienter löser in på sin egen backend. Begärans brödtext stöder formulärkodning, och följande variabler representerar data som applikationen erhållit från denna auktorisering:client_secret på serversidan. client_secret_post stöds för närvarande; behandla inte HTTP Basic-klientautentisering som en metod som stöds.
Läs access_token, token_type, expires_in och den faktiskt beviljade scope i det lyckade svaret. Endast om offline_access har begärts och beviljats finns en refresh_token. Behandla inte OAuth access token som API Key för modell-API:t, och skriv inte token, verifier eller auktoriseringskod till loggar, analyshändelser eller delningslänkar.
Steg 4: Läs användarinformation och API Key
Använd först OAuth access token för att begära UserInfo:id är användaridentifieraren; profile:read eller openid kan läsa grundläggande profiluppgifter (såsom username, nickname, avatar, is_verified, date_joined, registration_method); e-post kräver email:read, och telefonnummer samt region kräver phone:read. Förlita dig inte på att obehöriga fält alltid finns.
När en befintlig API Key behövs och credentials:read har beviljats, använd UserInfos id som filtervillkor:
count och items, och Key-fältet är items[*].token, inte data[0].value. user_id=me är inte ett giltigt användar-ID för detta gränssnitt. Fortsätt läsa flersidiga data enligt offset/limit; behandla inte första sidan som alla autentiseringsuppgifter.
Välj lämpliga autentiseringsuppgifter utifrån applikation, tjänst och giltighetsstatus; ta inte blint den första. En tom lista betyder inte att auktoriseringen misslyckades; användaren kan ännu inte ha skapat en lämplig Key. OAuth access tokens behörighetskontroll och API Key:ns egen tjänsteomfattning, kvot och utgångsvillkor är olika begränsningar.
Att tillåta läsning av API Key innebär att tredje part kan spara och använda den. Att återkalla OAuth-begäran eller rensa applikationens inloggningsstatus gör inte en redan kopierad API Key ogiltig; användaren måste återkalla eller rotera Key:n separat i autentiseringsuppgiftshanteringen.
Körbart Public / PKCE-webbläsarexempel
Distribuera följande sida till din registreradeREDIRECT_URI, och ersätt CLIENT_ID och återanropsadressen. Knappen initierar standardauktorisering och läser personlig information samt antalet befintliga Keys efter återkomst till samma sida. Exemplet visar inte och sparar inte Keys; produktionsapplikationer använder resultatet enligt det faktiska ändamålet. Verifiera först på en separat webbläsarsida och godkänn sedan enligt iframe-kraven längre fram.
sessionStorage. Produktionsapplikationer bör hantera token i sin egen sessionslösning, hantera utgångstid och rensa auktoriserings-URL-parametrar efter att ett svar har tagits emot; sidans huvudgränssnitt bör renderas först, och nätverksfel bör endast påverka anslutningsstatusen.
iframe på webbplats med white label
Kundens webbplats navigerar själv till auktoriseringssidan
Använd standardparametrar för OAuth och egen hantering av återanrop;window.location.assign() navigerar den aktuella iframe:n, och den överordnade sidan stannar kvar på white label-domänen. Det behövs inte att lägga till embed=studio för ikonen eller implementera Studio-meddelandeprotokollet.
Följande villkor måste uppfyllas:
- Applikationssidan och återanropssidan använder HTTPS, är faktiskt åtkomliga och tillåter inbäddning via iframe från white label-föräldradomänen; kontrollera båda sidors
Content-Security-Policy: frame-ancestorsochX-Frame-Options. - sandbox tillåter de skript, formulär och ursprungs-/lagringsfunktioner som sidan behöver. Vid stöd för popup-inloggning behövs även motsvarande popup-funktioner; använd i första hand konfigurationen för Website-komponenten som Studio tillhandahåller.
- Webbläsaren tillåter att lagringen som krävs för auktoriseringstillståndet används i det aktuella inbäddningsscenariot. White label-webbplatsens inloggningsstatus och AuthFrontends inloggningsstatus kan skilja sig åt; anta inte att auktoriseringssidan redan är inloggad bara för att white label-webbplatsen är inloggad.
- Tokenutbytestjänsten i återanropet är tillgänglig, och förfrågningar mellan olika ursprung tillåter applikationens ursprung; DNS-, CORS- och HTTP-fel måste visa ett tillstånd som går att försöka igen, och får inte hindra hela sidan från att renderas.
Använd det aktuella Studio-kontot för auktorisering
Aktivera OAuth i Studio under ”Inställningar → Startsida → Webbplatskomponenter”, och fyll iclient_id och den registrerade återanropsadressen. Webbplatsen och återanropet måste använda samma HTTPS-ursprung och skilja sig från Studio-ursprunget. Tredjepartssidan behöver:
- Skicka
acedatacloud:oauth:readytill det exakta ursprunget för den överordnade webbplatsen, och ta emot samt valideraacedatacloud:oauth:init. - Knappen genererar state och PKCE verifier, och skickar
acedatacloud:oauth:authorize(state, S256 challenge); verifiern stannar kvar på den egna sidan. - Validera det överordnade fönstret, ursprunget och state, hantera code eller error i
acedatacloud:oauth:result, och byt enligt standardtokenändpunkten. Studio visar auktoriseringssidan i komponentområdet, och efter att användaren samtyckt returneras auktoriseringskoden via meddelande, applikationen behöver inte omdirigeras. När ingen är inloggad returneraslogin_required, vid avslag returnerasaccess_denied, och vid väntetidsgräns returnerasauthorization_timeout. Kontobyte återskapar applikationens iframe och avbryter ofullständiga auktoriseringar.
profile:read credentials:read, och inkluderar inte offline_access. Anta inte att en refresh token säkert kan tas emot. embed=studio och embed_origin underhålls av Studio-värden och auktoriseringssidan, kundsidan behöver bara följa meddelandeprotokollet.
Fullständigt knappexempel finns i OAuth-integrationsguiden för Studio-webbkomponenter.
Livscykel, uppdatering och återkallelse
Access token har en standardgiltighet på 15 dagar och uppdatering eller ny auktorisering bör schemaläggas enligt varje svarsexpires_in; refresh token har som standard 30 dagar, och perioden påverkas av tjänstekonfigurationen. Hårdkoda inte dessa två värden som permanenta löften.
Efter att offline_access har beviljats kan följande anropas:
Vanliga fel och godkännande
Verifiera minst före leverans: korrekt återanrop, avslag, felaktigt state, utgången/förbrukad code, ingen Key, nätverksfel, utgången token, saknad nödvändig scope samt första inloggning och kontobyte i iframe-scenarier. Spara inte fullständig code, token eller API Key i testbevis.
Tvåstegsverifiering och ny auktorisering
Efter att användaren aktiverat tvåstegsverifiering genomför Ace Data Cloud verifiering av autentiserarens verifieringskod eller engångsåterställningskod på auktoriseringssidan, och levererar sedan auktoriseringskoden. Din applikation fortsätter att använda standardflödet för OAuth och bör inte be användaren om, spara eller vidarebefordra autentiserarens hemliga nycklar eller återställningskoder. När användaren aktiverar, byter eller inaktiverar tvåstegsverifiering eller återställer kontot, kan tidigare kontosessioner, refresh tokens och relaterade plattformsauktoriseringstoken bli ogiltiga. När ogiltig session ellerinvalid_grant tas emot, starta det användarsynliga auktoriseringsflödet på nytt, återanvänd inte gamla auktoriseringskoder upprepade gånger och försök inte kringgå verifieringen. Autentiseringssättet för vanliga modell-API Keys förblir oförändrat; om kontointrång misstänks bör berörda API Keys kontrolleras och återkallas separat.
