Om oss
- Om oss
- » Digitala samarbeten
- » Utveckling av API:er och öppna data
- » Säkerhet och API:er
- » Authorization Code Grant (ACG)
Authorization Code Grant (ACG)
Authorization Code 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. Våra steg för steg-guider förklarar hur flödet fungerar med antingen API-nycklar eller kombinationen API-nycklar och organisationslegitimation eller e-legitimation.
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.
Programvaran måste också generera så kallade state-parametrar. State-parametern är ett slumpmässigt värde som skickas mellan programvaran och auktorisationsservern för att förhindra så kallade CSRF-attacker (Cross-Site Request Forgery).
Så använder du flödet ACG
ACG-flödet används främst när den anropande programvaran är serverbaserad. I stora drag går det ut på att en organisation eller person autentiserar sig med hjälp av antingen organisationslegitimation eller e-legitimation mot Skatteverkets auktorisationsserver. Om det är en person som autentiserar sig med en e-legitimation behöver hen också lämna ett medgivande. När det är gjort får programvaran en auktorisationskod som den i sin tur växlar mot en access token (ett slags behörighetsbiljett) i auktorisationsservern. Med hjälp av access token får användaren slutligen åtkomst till API:et.
Kommunikationen mellan programvaran och API:et ska alltid vara krypterad med https och användaren kan använda en webbläsare, mobilapp eller vanlig klientprogramvara (som körs på till exempel Windows, OSx eller Linux) för att kommunicera med programvaran.
För dig som använder client ID, client secret och organisationslegitimation
Steg 1. Autentisera organisationen och begär en auktorisationskod
Vid anropet behöver du använda en organisationslegitimation från Expisoft för att autentisera programvaran.
Användaren av din programvara (i det här fallet en organisation) börjar autentiseringen mot Skatteverket genom att till exempel klicka på en knapp någonstans i programvaran. Detta triggar programvaran att starta en systemwebbläsare på klienten med ett anrop till auktorisationsservern.
Anropet ska innehålla: | |
|---|---|
Client ID | En del av dina API-nycklar. |
State-parameter | State-parametern är ett slumpmässigt värde som skickas mellan programvaran och auktorisationsservern för att för att förhindra så kallade CSRF-attacker (Cross-Site Request Forgery). |
Scope | Välj det eller de scope som står i API:ets tjänstebeskrivning. |
Redirect-URI | Välj den redirect-URI som du kopplade till API-nycklarna i samband med registreringen. Du måste alltid skriva redirect-URI:n på exakt samma sätt som du gjorde när du registrerade den hos oss. |
Så ska anropet se ut
Testmiljö: GET https://orgoauth2.test.skatteverket.se/oauth2/v1/org/authorize? client_id=<OAUTH2 CLIENT ID>&response_type=code&state=<STATE-PARAMETER>&redirect_uri=<REDIRECT-URI>&scope=<API SCOPE>
Produktionsmiljö: GET https://orgoauth2.skatteverket.se/oauth2/v1/org/authorize? client_id=<OAUTH2 CLIENT ID>&response_type=code&state=<STATE-PARAMETER>&redirect_uri=<REDIRECT-URI>&scope=<API SCOPE>
Steg 2. Ta emot en auktorisationskod
När autentiseringen är klar omdirigeras klienten till URI:n du angett i anropet och lägger samtidigt till en auktorisationskod som query-parameter tillsammans med state-parametern. Din programvara tar emot anropet på samma URI och kontrollerar att state-parametern är identisk med den som skickades med i anropet till auktorisationsservern.
Tänk på att en auktorisationskod bara är giltig i fem minuter.
Exempelsvar
<REDIRECT-URI>:?code=<AUKTORISATIONSKOD>&state=<STATE-PARAMETER>
Steg 3. Använd din auktorisationskod för att begära en access token
I nästa steg anropar programvaran auktorisationsservern (ändpunkten Token endpoint) med auktorisationskoden du just fått.
Anropet ska innehålla: | |
|---|---|
Auktorisationskod | Den du precis fått, används för att få en access token. |
Client ID | En del av dina API-nycklar. Den är märkt med OAuth2. |
Client secret | En del av dina API-nycklar. Den är märkt med OAuth2. |
Redirect-URI | Välj den redirect-URI som du kopplade till API-nycklarna i samband med registreringen. Du måste alltid skriva redirect-URI:n på exakt samma sätt som du gjorde när du registrerade den hos oss. |
Så ska anropet se ut
Testmiljö: POST https://orgoauth2.test.skatteverket.se/oauth2/v1/org/token
Produktionsmiljö: POST https://orgoauth2.skatteverket.se/oauth2/v1/org/token
HTTP-header: Content-Type: application/x-www-form-urlencoded
Body: grant_type=authorization_code&client_id=<OAUTH2 CLIENT ID>&client_secret=<OAUTH2 CLIENT SECRET>&redirect_uri=<REDIRECT-URI>&code=<AUKTORISATIONSKOD>
TIPS! Du kan använda din access token till flera tjänster genom att inkludera flera scope i bodyn.
Steg 4. 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
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 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 eftersom du bara kan hämta 200 access tokens per timme och användare.
VIKTIGT! Tänk på att din access token är en värdehandling.
Steg 5. 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 korrelations-id 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 e-legitimation
Steg 1. Autentisera användaren och begär en auktorisationskod
Användaren av din programvara (i det här fallet en person) börjar autentiseringen mot Skatteverket genom att till exempel klicka på en knapp någonstans i programvaran. Detta triggar programvaran att starta en systemwebbläsare på klienten med ett anrop till auktorisationsservern.
Anropet ska innehålla: | |
|---|---|
Client ID | En del av dina API-nycklar. |
State-parameter | State-parametern är ett slumpmässigt värde som skickas mellan programvaran och auktorisationsservern för att för att förhindra så kallade CSRF-attacker (Cross-Site Request Forgery). |
Scope | Välj det eller de scope som står i API:ets tjänstebeskrivning. |
Redirect-URI | Välj den redirect-URI som du kopplade till API-nycklarna i samband med registreringen. Du måste alltid skriva redirect-URI:n på exakt samma sätt som du gjorde när du registrerade den hos oss. |
Så här ska anropet se ut
Testmiljö: GET https://peroauth2.test.skatteverket.se/oauth2/v1/per/authorize?client_id=<OAUTH2 CLIENT ID>&response_type=code&state=<STATE-PARAMETER>&redirect_uri=<REDIRECT-URI>&scope=<API SCOPE>
Produktionsmiljö: GET https://peroauth2.skatteverket.se/oauth2/v1/per/authorize?client_id=<OAUTH2 CLIENT ID>&response_type=code&state=<STATE-PARAMETER>&redirect_uri=<redirect_uri>&scope=<API SCOPE>
Auktorisationsservern skickar användaren vidare till Skatteverkets inloggningssidor där hen autentiserar sig med en godkänd e-legitimation. Efter inloggning dirigeras användaren till en sida där hen får godkänna att programvaran anropar API:et för användarens räkning.
Steg 2. Ta emot auktorisationskoden
När autentiseringen är klar omdirigeras klienten till URI:n du angett i anropet och lägger samtidigt till en auktorisationskod som query-parameter tillsammans med state-parametern. Din programvara tar emot anropet på samma URI och kontrollerar att state-parametern är identisk med den som skickades med i anropet till auktorisationsservern.
Tänk på att en auktorisationskod bara är giltig i fem minuter.
Exempelsvar
<REDIRECT-URI>:?code=<AUKTORISATIONSKOD>&state=<STATE-PARAMETER>
Tänk på att en auktorisationskod bara är giltig i fem minuter.
Steg 3. Använd din auktorisationskod för att begära en access token
I nästa steg anropar programvaran auktorisationsservern (ändpunkten Token endpoint) med auktorisationskoden du just fått.
Anropet ska innehålla: | |
|---|---|
Auktorisationskod | Den du precis fått, används för att få en access token. |
Client ID | En del av dina API-nycklar. Den är märkt med OAuth2. |
Client secret | En del av dina API-nycklar. Den är märkt med OAuth2. |
Redirect-URI | Välj den redirect-URI som du kopplade till API-nycklarna i samband med registreringen. Du måste alltid skriva redirect-URI:n på exakt samma sätt som du gjorde när du registrerade den hos oss. |
Så ska anropet se ut
Testmiljö: POST https://peroauth2.test.skatteverket.se/oauth2/v1/per/token
Produktionsmiljö: POST https://peroauth2.skatteverket.se/oauth2/v1/per/token
HTTP-header: Content-Type: application/x-www-form-urlencoded
Body: grant_type=authorization_code&client_id=<OAUTH2 CLIENT ID>&client_secret=<OAUTH2 CLIENT SECRET>&redirect_uri=<REDIRECT-URI>&code=<AUKTORISATIONSKOD>
TIPS! Du kan använda din access token till flera tjänster genom att inkludera flera scope i bodyn.
Steg 4. 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
200 OK
Content-Type: application/json; charset=UTF-8
{
"access_token": <ACCESS TOKEN>,
"expires_in": 3600,
"token_type": "Bearer",
"scope": <API SCOPE>,
"refresh_token":"<REFRESH TOKEN>"
}
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 eftersom du bara kan hämta 20 access tokens per timme och användare.
VIKTIGT! Tänk på att din access token är en värdehandling.
Du får också en refresh token som du kan använda vid ett tillfälle om du behöver hämta ut en ny access token för att giltighetstiden gått ut. Det gör du genom att anropa auktorisationsservern och lägga till refresh token i anropet. Auktorisationsservern svarar då med en ny access token. Refresh token har en giltighetstid på 65 minuter. Det går att hämta maximalt 10 refresh tokens per användare under en pågående session.
Steg 5. 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 korrelations-id 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.
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
-
Imorgon öppnar ansökan för elstöd till företag
På tisdag 30 maj klockan 12.00 öppnar Skatteverkets e-tjänst för de som vill ans...
-
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...
Tillsammans gör vi samhället möjligt