- Om oss
- » Digitala samarbeten
- » Utveckling av API:er och öppna data
- » Säkerhet och API:er
- » Client Credentials Grant (CCG)
Client Credentials Grant (CCG)
Client Credentials Grant är ett av de OAuth2-flöden som Skatteverket använder för att du ska få tillgång till våra API:er. Ta hjälp av steg för steg-guiderna för att veta hur flödet fungerar med antingen API-nycklar eller kombinationen API-nycklar och organisationslegitimation.
Bra att veta innan du börjar
Din programvara måste kunna generera ett unikt värde för varje enskilt anrop till API:et, ett så kallat korrelationsid. Ett korrelationsid ska vara i string-format i valfri längd men max 36 tecken långt. Du kommer behöva värdet när du ska anropa API:et.
Så här använder du flödet CCG
CCG innebär i korthet att din programvara autentiserar sig mot Skatteverkets auktorisationsserver med API-nycklar och i vissa fall en organisationslegitimation från Expisoft för att få ut en så kallad access token. Med hjälp av access token får din programvara sedan åtkomst till API:et.
Våra partner-API:er stödjer tre olika autentiseringsmetoder inom CCG-flödet.
- Autentisering med Client ID och Client Secret (API-nycklar)
- Autentisering med Client ID och en utpekad organisationslegitimation (som ersätter Client Secret)
- Autentisering med Client ID, Client Secret och valfri organisationslegitimation
Varje partner-API är knuten till ett specifikt flöde och autentiseringsmetod, du kan alltså inte välja fritt. Vad som gäller för respektive API kan du läsa om här:
För dig som använder Client ID och Client Secret
Steg 1. Begär en access token
Det gör du genom att göra ett POST-anrop till Skatteverkets auktorisationsserver (ändpunkten Token Endpoint). Anropet ska innehålla dina API-nycklar som är märkta med "OAuth2". Du ska också skicka med scopet som är kopplat till ditt API.
Så här ska du göra anropet
Testmiljö: POST https://sysoauth2.test.skatteverket.se/oauth2/v1/sys/token
Produktionsmiljö: POST https://sysoauth2.skatteverket.se/oauth2/v1/sys/token
HTTP-header: Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Body: grant_type=client_credentials&client_id=<OAUTH2 CLIENT ID>&client_secret=<OAUTH2 CLIENT SECRET>&scope=<API SCOPE>
Steg 2. Ta emot en access token
Efter att auktorisationsservern stämt av uppgifterna du skickade i anropet får du ett svar i form av en JSON-body. Bodyn innehåller bland annat access token.
Exempelsvar efter lyckat anrop
200 OK
Content-Type: application/json; charset=UTF-8
{
"access_token": <ACCESS TOKEN>,
"expires_in": 3600,
"token_type": "Bearer",
"scope": <API SCOPE>
}
Tänk på att du bara kan använda en access token en timme, efter detta måste du hämta en ny. Det är samtidigt viktigt att du utnyttjar den här timmen och inte hämtar nya access tokens för varje anrop eftersom du bara kan hämta 200 access tokens per timme.
Steg 3. Anropa API:et
Nu när du har access token kan du anropa API:et. Du använder den som värde i en HTTP-header som du skickar med i anropet. Du ska också skicka med den andra delen av dina API-nycklar, de som är märkta med "APIgw" och ett korrelationsid som din programvara genererat. Anropet går via Skatteverkets API-gateway som kontrollerar access token och scope. Stämmer uppgifterna skickas anropet sedan vidare till API:et och du är redo att börja använda det.
Så här ska dina HTTP-headers se ut
Authorization: Bearer <ACCESS TOKEN>
Client_Id: <APIGW CLIENT ID>
Client_Secret: <APIGW CLIENT SECRET>
skv_client_correlation_id: <KORRELATIONSID>
För dig som använder Client ID och organisationslegitimation
Steg 1. Begär en access token
Det gör du genom att göra ett POST-anrop mot Skatteverkets auktorisationsserver (ändpunkten Token Endpoint). Anropet ska innehålla ditt OAuth2 Client ID (en del av dina API-nycklar) och API:ets scope. Auktorisationsservern begär sedan att programvaran autentiserar sig enligt standarden TLS/SSL och programvaran autentiserar sig då med er organisationslegitimation. Användningen av organisationslegitimation i den här lösningen gör att du inte ska använda något OAuth2 Client Secret i anropet.
Tänk på att du behöver koppla er organisationslegitimation till ditt OAuth Client ID om du ska använda just den här lösningen. Det gör du genom att fylla i fältet "Uppgift om er organisationslegitimation" när du ansöker om att ansluta till API:et.
Så här ska du göra anropet
Testmiljö: POST https://sysorgoauth2.test.skatteverket.se/oauth2/v1/sysorg/token
Produktionsmiljö: POST https://sysorgoauth2.skatteverket.se/oauth2/v1/sysorg/token
HTTP-header: Content-Type: application/x-www-form-urlencoded;charset=UTF-8
Body: grant_type=client_credentials&client_id=<OAUTH2 CLIENT ID>&scope=<API SCOPE>
Steg 2. Ta emot en access token
Du får svar från auktorisationsservern i form av en JSON-body med bland annat den access token du behöver för att kunna anropa API:et.
Exempelsvar efter lyckat anrop:
Content-Type: application/json; charset=UTF-8
{
"access_token": <ACCESS TOKEN>,
"expires_in": 3600,
"token_type": "Bearer",
"scope": <SCOPE>
}
Tänk på att du bara kan använda en access token en timme, efter detta måste du hämta en ny. Det är samtidigt viktigt att du utnyttjar den här timmen och inte hämtar nya access tokens för varje anrop eftersom du bara kan hämta 200 access tokens per timme.
Steg 3. Anropa API:et
Nu när du har access token kan du anropa API:et. Du använder den som värde i en HTTP-header som du skickar med i anropet. Du ska också skicka med API-nycklarna märkta "APIgw" och ett korrelationsid som din programvara genererat. Anropet går via Skatteverkets API-gateway som kontrollerar access token och scope, och stämmer uppgifterna skickas anropet vidare till API:et.
Så här ska dina HTTP-headers se ut
Authorization: Bearer <ACCESS TOKEN>
Client_Id: <APIGW CLIENT ID>
Client_Secret: <APIGW CLIENT SECRET>
skv_client_correlation_id: <KORRELATIONSID>
Så kan du som befintlig kund börja använda det nya auktorisationsflödet
Du vill använda flera flöden för samma API
Du använder ett API med ACG och e-legitimation. Du vill nu använda CCG med organisationslegitimation som komplement till ACG.
Så gör du
Du ber om ett nytt client id som du kopplar till er organisationslegitimation. Flödet används parallellt med ACG-flödet så länge det behövs.
Du vill byta flöde på ett API du redan använder
Du är redan ansluten till ett av Skatteverkets API:er där ACG-flödet används. API:et har numera också möjlighet att användas med CCG-flöde med organisationslegitimation. Du vill därför byta autentiseringsflöde.
Du måste begära ut nya client ID när du byter till det nya flödet. Det beror på att organisationslegitimationen ersätter client secret för detta client ID.
Så gör du för att koppla ihop Client ID med organisationslegitimation
1. Kopiera uppgifterna
Skatteverket behöver veta vilket namn och organisationsnummer som är skrivet i legitimationen du vill använda. Vi rekommenderar att du kopierar uppgifterna istället för att skriva dem. Kopplingen kräver nämligen att du anger uppgifterna på exakt samma sätt, det räcker med ett extra tecken eller en missad versal för att det inte ska fungera.
Du hittar informationen i en av p12-filerna du fått från Expisoft. Öppna filen märkt med namnet på organisationen som organisationslegitimationen är kopplat till, och kopiera raden ”subject”:
Subject: CN=Organisation A + SERIALNUMBER=165560000000, O=Organisation A, C=SE
Tips!
Om du använder Windows kan du hitta rätt innehåll med hjälp av Certutil eller Powershell.
- Kommandotolken: använd kommandot certutil – dump
- PowerShell: använd kommandot Get-PfxCertificate
2. Skicka uppgifterna
Du skickar sedan ett mejl till api@skatteverket.se och ber oss göra kopplingen.
Skriv ”Koppling av organisationslegitimation för CCG-flöde” i ämnesraden.
Skicka också den här informationen:
- Ert namn och organisationsnummer
- Ert nuvarande OAuth2 Client Id
- De sex sista siffrorna i ert OAuth2 Client secret (används för kontroll)
- Om ni vill göra kopplingen till ert nuvarande OAuth2 Client ID eller om ni vill ha ett nytt
- Det namn och nummer som är skrivet i er organisationslegitimation (kopieras)
För dig som använder Client ID, Client Secret och organisationslegitimation
Steg 1. Begär en access token
Det gör du genom att göra ett POST-anrop mot Skatteverkets auktorisationsserver (ändpunkten Token Endpoint). Anropet ska innehålla ditt OAuth2 Client ID (en del av dina API-nycklar), OAuth2 Client Secret och API:ets scope. Vid anropet ska du också använda en organisationslegitimation från Expisoft för att autentisera programvaran.
Så här ska du göra anropet
Testmiljö: POST https://sysorgoauth2.test.skatteverket.se/oauth2/v1/sysorg/token
Produktionsmiljö: POST https://sysorgoauth2.skatteverket.se/oauth2/v1/sysorg/token
HTTP-header: application/x-www-form-urlencoded
Body: grant_type=client_credentials&client_id=<OAUTH2 CLIENT ID>&client_secret=<OAUTH2 CLIENT SECRET>&scope=<API SCOPE>
Steg 2. Ta emot en access token
Du får svar från auktorisationsservern i form av en JSON-body med bland annat den access token du behöver för att kunna anropa API:et.
Exempelsvar efter lyckat anrop:
Content-Type: application/json; charset=UTF-8
{
"access_token": <ACCESS TOKEN>,
"expires_in": 3600,
"token_type": "Bearer",
"scope": <SCOPE>
}
Tänk på att du bara kan använda en access token under den tid som anges i svaret (expires in), efter detta måste du hämta en ny. Det är viktigt att du utnyttjar den här tiden och inte hämtar nya access tokens för varje anrop.
Steg 3. Anropa API:et
Nu när du har access token kan du anropa API:et. Du använder den som värde i en HTTP-header som du skickar med i anropet. Du ska också skicka med API-nycklarna märkta "APIgw" och ett korrelationsid som din programvara genererat. Anropet går via Skatteverkets API-gateway som kontrollerar access token och scope, och stämmer uppgifterna skickas anropet vidare till API:et.
Så här ska dina HTTP-headers se ut
Authorization: Bearer <ACCESS TOKEN>
Client_Id: <APIGW CLIENT ID>
Client_Secret: <APIGW CLIENT SECRET>
skv_client_correlation_id: <KORRELATIONSID>
Vi hjälper dig gärna vid frågor
Våra kunniga utvecklare på supporten hjälper dig gärna om du har frågor. Du kan även höra av dig till oss om du vill ha de gamla säkerhetsdokumenten som tidigare hittades på Utvecklarportalen i pdf-format.
Relaterat innehåll
Kontakta oss
Webbseminarier för företagare
Vill du lära dig mer om skatter och företagande? Ta då chansen och möt oss online på våra direktsända webbseminarier. Det är kostnadsfritt och du kan ställa frågor och få svar i en chatt.
Aktuellt
-
Finansministern följde med på kontrollbesök
Finansminister Elisabeth Svantesson följde nyligen med vid ett kontrollbesök av ...
-
Deklarationen: Reseavdrag med bil kräver tidsvinst på två timmar
Årets deklaration öppnade den 14 mars. Många kan godkänna sin förifyllda deklara...
-
Tillfälliga brevlådor redan från den 21 mars
Den som vill deklarera på papper rekommenderas av Skatteverket att i första hand...
Tillsammans gör vi samhället möjligt