Om oss
- 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 partner-API:er. Våra steg för steg-guider förklarar 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 korrelations-id. Ett korrelations-id 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. I vissa fall behövs också 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, client secret och valfri organisationslegitimation
- Autentisering med client ID och en utpekad organisationslegitimation (som ersätter client secret)
Varje partner-API är knuten till ett eller flera specifika flöden och autentiseringsmetoder, 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 med ett POST-anrop till Skatteverkets auktorisationsserver (ändpunkten Token endpoint).
Anropet ska innehålla: | |
|---|---|
Client ID | Ena delen av dina API-nycklar. Den är märkt med OAuth2. |
Client secret | Andra delen av dina API-nycklar. Den är märkt med OAuth2. |
Scope | Välj det eller de scope som står i API:ets tjänstebeskrivning. |
Så här gör du 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>
TIPS! Du kan använda din access token till flera tjänster genom att inkludera flera scope i bodyn.
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 din access token. Svaret innehåller också det eller de scope du har begärt. Det är bra om du verifierar att det stämmer med anropet du skickade.
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>
}
Du kan bara använda en access token under den tid som anges i svaret (expires in), efter detta måste du hämta en ny access token. Det är viktigt att du utnyttjar den här tiden och inte hämtar nya access tokens för varje anrop.
VIKTIGT! Tänk på att din access token är en värdehandling.
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. 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.
Anropet ska innehålla: | |
|---|---|
Access token | Den du precis fått. Tänk på att du bara kan använda samma access token under den tid som anges i svaret. |
APIGW Client ID | Den andra delen av dina API-nycklar, som är märkt med APIgw. |
APIGW Client secret | Den andra delen av dina API-nycklar, som är märkt med APIgw. |
Korrelations-id | Din programvara måste kunna generera ett unikt värde för varje enskilt anrop till API:et, ett så kallat korrelations-id. Ett korrelationsid ska vara i string-format och i valfri längd, men max 36 tecken långt.
|
Så 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>
Här visar vi bara de parametrar som krävs för autentisering. För själva API-anropet krävs det fler parametrar. Du hittar dem i API:ets tjänstebeskrivning. I tjänstebeskrivningen kan du också kontrollera parametern för korrelations-id, eftersom den finns i flera versioner.
VIKTIGT! Skicka endast med de header-parametrar som är angivna för respektive tjänst, annars kan anropet blockeras.
För dig som använder client ID, client secret och valfri organisationslegitimation
Steg 1. Begär en access token
Det gör du med ett POST-anrop till Skatteverkets auktorisationsserver (ändpunkten Token endpoint). Vid anropet ska du också använda en organisationslegitimation från Expisoft för att autentisera programvaran.
Anropet ska innehålla: | |
|---|---|
Client ID | Ena delen av dina API-nycklar. Den är märkt med OAuth2. |
Client secret | Andra delen av dina API-nycklar. Den är märkt med OAuth2. |
Scope | Välj det eller de scope som står i API:ets tjänstebeskrivning. |
Så här gör du 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>
TIPS! Du kan använda din access token till flera tjänster genom att inkludera flera scope i bodyn.
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. Svaret innehåller också det eller de scope du har begärt. Det är bra om du verifierar att det stämmer med anropet du skickade.
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 access token. Det är viktigt att du utnyttjar den här tiden och inte hämtar nya access tokens för varje anrop.
VIKTIGT! Tänk på att din access token är en värdehandling.
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. Anropet går via Skatteverkets API-gateway som kontrollerar access token och scope. Stämmer uppgifterna skickas anropet vidare till API:et.
Anropet ska innehålla: | |
|---|---|
Access token | Den du precis fått. Tänk på att du bara kan använda samma access token under den tid som anges i svaret. |
APIGW Client ID | Den andra delen av dina API-nycklar, som är märkt med APIgw. |
APIGW Client secret | Den andra delen av dina API-nycklar, som är märkt med APIgw. |
Korrelations-id | Din programvara måste kunna generera ett unikt värde för varje enskilt anrop till API:et, ett så kallat korrelations-id. Ett korrelationsid ska vara i string-format och i valfri längd, men max 36 tecken långt. |
Så 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>
Här visar vi bara de parametrar som krävs för autentisering. För själva API-anropet krävs det fler parametrar. Du hittar dem i API:ets tjänstebeskrivning. I tjänstebeskrivningen kan du också kontrollera parametern för korrelations-id, eftersom den finns i flera versioner.
VIKTIGT! Skicka endast med de header-parametrar som är angivna för respektive tjänst, annars kan anropet blockeras.
För dig som använder client ID och utpekad organisationslegitimation
Steg 1. Begär en access token
Du behöver koppla er organisationslegitimation till ditt OAuth client ID om du ska använda 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.
För att begära en access token gör du ett POST-anrop mot Skatteverkets auktorisationsserver (ändpunkten Token endpoint). 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.
Anropet ska innehålla: | |
|---|---|
Client ID | Ena delen av dina API-nycklar. Den är märkt med OAuth2. |
Scope | Välj det eller de scope som står i API:ets tjänstebeskrivning. |
Så här gör du 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>
TIPS! Du kan använda din access token till flera tjänster genom att inkludera flera scope i bodyn.
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. Svaret innehåller också det eller de scope du har begärt. Det är bra om du verifierar att det stämmer med anropet du skickade.
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.
VIKTIGT! Tänk på att din access token är en värdehandling.
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. Anropet går via Skatteverkets API-gateway som kontrollerar access token och scope, och stämmer uppgifterna skickas anropet vidare till API:et.
Anropet ska innehålla: | |
|---|---|
Access token | Den du precis fått. Tänk på att du bara kan använda samma access token under den tid som anges i svaret. |
APIGW client ID | Den andra delen av dina API-nycklar, som är märkt med APIgw. |
APIGW client secret | Den andra delen av dina API-nycklar, som är märkt med APIgw. |
Korrelations-id | Din programvara måste kunna generera ett unikt värde för varje enskilt anrop till API:et, ett så kallat korrelations-id. Ett korrelationsid ska vara i string-format och i valfri längd men max 36 tecken långt. |
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>
Här visar vi bara de parametrar som krävs för autentisering. För själva API-anropet krävs det fler parametrar. Dem hittar du i den aktuella tjänstebeskrivningen. Där kan du också kontrollera parametern för korrelations-id, eftersom den finns i flera versioner och det inte är säkert att exemplet här stämmer med det API du vill använda.
VIKTIGT! Skicka endast med de header-parametrar som är angivna för respektive tjänst, annars kan anropet blockeras.
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
-
Samfälligheter ska momsregistreras
Samfällighetsföreningar som förvaltar en gemenskapsanläggning ska numera registr...
-
Ny Mervärdesskattelag från 1 juli
Riksdagen har beslutat om en ny mervärdesskattelag. Den nya lagen är en omarbetn...
-
Missa inte intyg för rätt skatt på sommarjobbet
Den som tjänar mindre än 22 208 kronor på ett sommarjobb och inte har andra inko...
Tillsammans gör vi samhället möjligt