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.
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.
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.
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:
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.
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>
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.
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.
Authorization: Bearer <ACCESS TOKEN>
Client_Id: <APIGW CLIENT ID>
Client_Secret: <APIGW CLIENT SECRET>
skv_client_correlation_id: <KORRELATIONSID>
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.
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>
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.
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.
Authorization: Bearer <ACCESS TOKEN>
Client_Id: <APIGW CLIENT ID>
Client_Secret: <APIGW CLIENT SECRET>
skv_client_correlation_id: <KORRELATIONSID>
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 ä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.
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.
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:
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>
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.
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.
Authorization: Bearer <ACCESS TOKEN>
Client_Id: <APIGW CLIENT ID>
Client_Secret: <APIGW CLIENT SECRET>
skv_client_correlation_id: <KORRELATIONSID>
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.
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.