Hoppa till huvudinnehåll
Låt användare ge din applikation behörighet att komma åt deras Ace Data Cloud-profil, tjänsteprenumerationer, API Key, användning eller beställningar. Använd standard Authorization Code + S256 PKCE: applikationen öppnar auktoriseringssidan, användaren samtycker och får sedan en engångs-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änssnitt GET /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:
  1. om behörigheten får delegeras till denna applikationstyp;
  2. om behörigheten har registrerats inom de tillåtna omfången för denna OAuth-applikation;
  3. om den aktuella användaren har den begärda behörigheten.
Okända, oregistrerade, ej tillåtna att delegera eller behörigheter som användaren saknar returnerar 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änd available_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.
Spara 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ässiga state och code_verifier, beräkna:
Spara state, verifier och återanropsadress i applikationens egen session, och öppna sedan auktoriseringssidan med URL-kodade parametrar:
Public-klienter måste skicka S256 PKCE. Även om Discovery fortfarande listar 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:
Confidential-klienter måste även lägga till formulärfältet 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:
De returnerade fälten beror på scope: 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:
Den returnerade listan använder 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 registrerade REDIRECT_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.
Exemplets återanrop och ingång måste ha samma ursprung och finnas i samma webbläsarflik/iframe för att kunna läsa den tidigare sparade 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-ancestors och X-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.
Auktoriseringssidan läser OAuth-applikationens Logo till vänster; till höger läser den Site:ns favicon/logo när webbläsaren kan tillhandahålla föräldraursprunget och föräldradomänen godkänns genom verifierad webbplatsvalidering, annars visas en standardikon. Detta avgör endast varumärkesvisningen, etablerar ingen inloggningssession och ger inte kundsidan kontobehörigheter. Nuvarande begränsning: När vanlig OAuth behöver logga in igen i en iframe finns det fortfarande en lucka i flödet för att återgå till auktoriseringssidan efter att inloggningen har slutförts. Före lansering måste både ”Auth inloggad” och ”Auth inte inloggad/utgången” godkännas separat. Innan denna lucka har åtgärdats och verifierats kan den första inloggningen slutföras med standard-OAuth på en separat sida, eller med Studio-komponentens auktorisering nedan; lova inte att alla iframe-scenarier fungerar enbart baserat på testresultat där användaren redan är inloggad.

Använd det aktuella Studio-kontot för auktorisering

Aktivera OAuth i Studio under ”Inställningar → Startsida → Webbplatskomponenter”, och fyll i client_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:
  1. Skicka acedatacloud:oauth:ready till det exakta ursprunget för den överordnade webbplatsen, och ta emot samt validera acedatacloud:oauth:init.
  2. Knappen genererar state och PKCE verifier, och skickar acedatacloud:oauth:authorize (state, S256 challenge); verifiern stannar kvar på den egna sidan.
  3. 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 returneras login_required, vid avslag returneras access_denied, och vid väntetidsgräns returneras authorization_timeout. Kontobyte återskapar applikationens iframe och avbryter ofullständiga auktoriseringar.
Komponenten begär för närvarande 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 svars expires_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:
Uppdatering returnerar nya token, applikationen bör spara de senaste värdena. Vid uppdatering kontrolleras om applikationen fortfarande är giltig, användaren är tillgänglig och behörigheterna fortfarande är beviljade. Vid fel ska det egna anslutningstillståndet rensas och auktorisering göras på nytt. Den nuvarande OAuth-uppdateringsimplementeringen garanterar inte att den gamla refresh token omedelbart blir ogiltig efter uppdatering. Betrakta inte att en ny token har erhållits som att den gamla token har återkallats, och använd inte rotering av secret som ersättning för att avsluta befintliga token. Återkallelsebegäran anropas så här:
Den nuvarande återkallelseändpunkten returnerar HTTP 200, men implementerar inte omedelbar ogiltigförklaring av utfärdade JWT:er. Applikationen bör rensa sina egna sparade token och kan inte betrakta 200 som bevis på att alla utfärdade token eller API Keys har blivit ogiltiga. API Keys som har läckt eller kopierats ska återkallas eller roteras separat med motsvarande autentiseringsuppgifter.

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 eller invalid_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.