Autorisasjon Guider Systemleverandør Tilgangsstyring

Tilgangsstyrings-API

Slik bruker du tilgangsstyrings-API-et fra sluttbrukersystem

Altinn tilbyr et tilgangsstyrings-API som lar sluttbrukersystemer administrere tilganger mellom parter. API-et gir mulighet til å se og håndtere hvem som har tilgang til hva, delegere tilgangspakker og enkeltrettigheter, og administrere klientforhold.

Hva er et sluttbrukersystem?

Et sluttbrukersystem er programvare eller en nettside som kaller Altinns API-er på vegne av en bruker eller virksomhet. Det kan for eksempel være et regnskapssystem, en HR-løsning eller en portal fra en tjenesteeier med innlogging via ID-porten. Det finnes to typer:

Systemer med ID-porten-pålogging: Nettløsninger eller applikasjoner der en person logger inn med ID-porten. Systemet handler på vegne av den påloggede brukeren. Dette kan være alt fra et regnskapssystem til en offentlig portal som tilbyr selvbetjeningsfunksjoner.
Systemer med systembruker: Bakgrunnssystemer som bruker en systembruker til å kalle API-et uten at en person er pålogget. Systemet handler på vegne av virksomheten som har opprettet systembrukeren.

Når er denne integrasjonen aktuell?

Tilgangsstyrings-API-et er relevant for systemer som ønsker å automatisere administrasjon av tilganger i Altinn. Eksempler:

Store virksomheter som ønsker å automatisere hvilke tilganger ansatte har. I stedet for å logge inn i Altinn og delegere tilgangspakker manuelt kan virksomheten bruke API-et til å synkronisere tilganger fra egne HR- eller identitetssystemer.
Tjenestetilbydere (regnskapsførere, revisorer o.l.) som administrerer tilganger for mange klienter og ønsker å gjøre dette effektivt gjennom egne systemer.
Forvaltningsløsninger som trenger å vise brukeren hvilke parter de kan handle på vegne av, og hvilke rettigheter de har.

OpenAPI

EndUser

Hvem kan bruke API-et?

API-et kan brukes av personer (via ID-porten) eller systembrukere (via Maskinporten).

Autentisering med ID-porten

Personen logger inn via ID-porten. Under innlogging må sluttbrukeren gi samtykke til scopene som systemet ber om. Disse scopene avgrenser hva systemet kan gjøre på vegne av brukeren.

Se autentisering med ID-porten for detaljer om scopes og samtykke.

ID-porten-tokenet må deretter veksles til et Altinn-token.

Relevante scopes

Systemet må be om de scopene som trengs for funksjonaliteten det skal bruke.

Autoriserte parter:

altinn:accessmanagement/authorizedparties — hente parter brukeren er autorisert for

Tilkoblinger — se tilganger gitt fra andre:

altinn:accmgmt/enduser:connections:from-others.read — lese tilkoblinger fra andre
altinn:accmgmt/enduser:connections:from-others.write — endre tilkoblinger fra andre

Tilkoblinger — administrere tilganger gitt til andre:

altinn:accmgmt/enduser:connections:to-others.read — lese tilkoblinger til andre
altinn:accmgmt/enduser:connections:to-others.write — endre tilkoblinger til andre

Autentisering med systembruker

API-et kan også brukes med en systembruker. Systembrukertokenet hentes fra Maskinporten og må deretter veksles til et Altinn-token. Se bruk av systembruker for detaljer om tokenveksling.

Krav til tilgangspakke

For å bruke de fleste endepunktene i tilgangsstyrings-API-et må den innloggede brukeren eller systembrukeren ha en av følgende tilgangspakker for den aktuelle virksomheten:

Tilgangsstyring (urn:altinn:accesspackage:tilgangsstyring)
Hovedadministrator (urn:altinn:accesspackage:hovedadministrator)

Identifikatorer

API-et bruker partyUuid som identifikator for parter. Hver person eller virksomhet i Altinn har en unik UUID.

Du finner partyUuid for aktuelle parter via Authorized Parties-endepunktet som er beskrevet nedenfor.

API: Hente autoriserte parter

Henter alle parter (virksomheter og personer) som den innloggede brukeren er autorisert for.

Test: GET https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/authorizedparties
Produksjon: GET https://platform.altinn.no/accessmanagement/api/v1/enduser/authorizedparties

Spørreparametere

Parameter	Type	Standardverdi	Beskrivelse
`includeRoles`	boolean	false	Inkluder roller i responsen
`includeAccessPackages`	boolean	false	Inkluder tilgangspakker i responsen
`includeResources`	boolean	false	Inkluder ressurser i responsen
`includeInstances`	boolean	false	Inkluder instanser i responsen
`includePartiesViaKeyRoles`	false/true/auto	auto	Inkluder parter via nøkkelroller
`includeSubParties`	false/true/auto	auto	Inkluder underparter
`includeInactiveParties`	false/true/auto	auto	Inkluder inaktive parter
`partyFilter`	array (UUID)	null	Filtrer på spesifikke parter
`anyOfResourceIds`	array (string)	null	Filtrer på ressurs-ID-er

Hvis du ønsker å finne hvilke parter den påloggede brukeren har tilgangsstyringsrettigheter for, kan du bruke anyOfResourceIds-filteret med ressurs-ID-en for tilgangsstyring:

GET .../enduser/authorizedparties?anyOfResourceIds=urn:altinn:resource:accessmanagement/authorizedparties

Da returneres kun parter der brukeren har rettigheter til å styre tilganger.

Eksempelrespons

{
  "links": {
    "next": null
  },
  "data": [
    [
      {
        "partyUuid": "4a06214d-b261-4695-b33a-0771a995b503",
        "name": "GEOMETRISK VOKSENDE TIGER AS",
        "organizationNumber": "310757632",
        "partyId": 51561408,
        "type": "Organization",
        "unitType": "AS",
        "isDeleted": false,
        "onlyHierarchyElementWithNoAccess": false,
        "authorizedAccessPackages": [
          "urn:altinn:accesspackage:skattegrunnlag"
        ],
        "authorizedRoles": [
          "urn:altinn:role:tilgangsstyrer"
        ],
        "subunits": []
      }
    ]
  ]
}

API: Hente tilkoblinger

Henter alle tilkoblinger (relasjoner) for en gitt part. En tilkobling viser hvem som har tilgang til hva, inkludert roller, tilgangspakker og ressurser.

Test: GET https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections
Produksjon: GET https://platform.altinn.no/accessmanagement/api/v1/enduser/connections

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`from`	UUID	Nei	Filtrer på avsender
`to`	UUID	Nei	Filtrer på mottaker
`includeClientDelegations`	boolean	Nei (standard: true)	Inkluder klientdelegeringer
`includeAgentConnections`	boolean	Nei (standard: true)	Inkluder agenttilkoblinger

Paginering styres med X-Page-Size og X-Page-Number i headere.

Eksempelrespons

{
  "links": {
    "next": null
  },
  "data": [
    {
      "party": {
        "id": "01f7a70d-2619-4c50-8ff4-efd7ae6c8960",
        "name": "KREATIV GRANITT",
        "type": "Person",
        "variant": "Person"
      },
      "roles": [
        {
          "id": "42cae370-2dc1-4fdc-9c67-c2f4b0f0f829",
          "code": "rettighetshaver",
          "urn": "urn:altinn:role:rettighetshaver"
        }
      ],
      "packages": [
        {
          "id": "4c859601-9b2b-4662-af39-846f4117ad7a",
          "urn": "urn:altinn:accesspackage:skattegrunnlag"
        }
      ],
      "resources": []
    }
  ]
}

API: Opprette tilkobling

Oppretter en ny tilkobling (delegering) til en person. Oppgi fødselsnummer og etternavn.

Test: POST https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections
Produksjon: POST https://platform.altinn.no/accessmanagement/api/v1/enduser/connections

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`to`	UUID	Nei	partyUuid for mottaker (alternativ til body)

Eksempelforespørsel (body)

{
  "personIdentifier": "01038712345",
  "lastName": "Salt"
}

Eksempelrespons

{
  "id": "019c2e70-c577-7b20-a11c-245fecd5e564",
  "roleId": "ff4c33f5-03f7-4445-85ed-1e60b8aafb30",
  "fromId": "4a06214d-b261-4695-b33a-0771a995b503",
  "toId": "01f7a70d-2619-4c50-8ff4-efd7ae6c8960"
}

API: Slette tilkobling

Sletter en tilkobling mellom to parter.

Test: DELETE https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections
Produksjon: DELETE https://platform.altinn.no/accessmanagement/api/v1/enduser/connections

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`from`	UUID	Ja	partyUuid for avsenderen
`to`	UUID	Ja	partyUuid for mottakeren
`cascade`	boolean	Nei	Slett også underliggende delegeringer

API: Hente tilgangspakker for en tilkobling

Henter tilgangspakker som er delegert mellom to parter.

Test: GET https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections/accesspackages
Produksjon: GET https://platform.altinn.no/accessmanagement/api/v1/enduser/connections/accesspackages

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`from`	UUID	Nei	partyUuid for avsenderen
`to`	UUID	Nei	partyUuid for mottakeren

Paginering styres med X-Page-Size og X-Page-Number i headere.

API: Delegere tilgangspakke

Delegerer en tilgangspakke til en person.

Test: POST https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections/accesspackages
Produksjon: POST https://platform.altinn.no/accessmanagement/api/v1/enduser/connections/accesspackages

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`to`	UUID	Nei	partyUuid for mottaker (alternativ til body)
`packageId`	UUID	Nei	ID for tilgangspakken
`package`	string	Nei	URN for tilgangspakken

Eksempelforespørsel (body)

{
  "personIdentifier": "01038712345",
  "lastName": "Salt"
}

Eksempelrespons

{
  "id": "019c2e70-c577-7b20-a11c-245fecd5e564",
  "assignmentId": "ff4c33f5-03f7-4445-85ed-1e60b8aafb30",
  "packageId": "4c859601-9b2b-4662-af39-846f4117ad7a"
}

API: Fjerne tilgangspakke

Fjerner en delegert tilgangspakke fra en tilkobling.

Test: DELETE https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections/accesspackages
Produksjon: DELETE https://platform.altinn.no/accessmanagement/api/v1/enduser/connections/accesspackages

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`from`	UUID	Ja	partyUuid for avsenderen
`to`	UUID	Ja	partyUuid for mottakeren
`packageId`	UUID	Nei	ID for tilgangspakken
`package`	string	Nei	URN for tilgangspakken

API: Kontrollere delegeringsmulighet for tilgangspakker

Sjekker om den innloggede brukeren kan delegere en gitt tilgangspakke på vegne av parten.

Test: GET https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections/accesspackages/delegationcheck
Produksjon: GET https://platform.altinn.no/accessmanagement/api/v1/enduser/connections/accesspackages/delegationcheck

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`packageIds`	array (UUID)	Nei	ID-er for tilgangspakkene
`packages`	array (string)	Nei	URN-er for tilgangspakkene

Eksempelrespons

{
  "links": {
    "next": null
  },
  "data": [
    {
      "package": {
        "id": "4c859601-9b2b-4662-af39-846f4117ad7a",
        "urn": "urn:altinn:accesspackage:skattegrunnlag"
      },
      "result": true,
      "reasons": []
    }
  ]
}

API: Hente roller for en tilkobling

Henter roller som en part har fått delegert i en tilkobling.

Test: GET https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections/roles
Produksjon: GET https://platform.altinn.no/accessmanagement/api/v1/enduser/connections/roles

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`from`	UUID	Ja	partyUuid for avsenderen
`to`	UUID	Ja	partyUuid for mottakeren

Paginering styres med X-Page-Size og X-Page-Number i headere.

API: Hente ressurser for en tilkobling

Henter ressurser som er delegert mellom to parter.

Test: GET https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections/resources
Produksjon: GET https://platform.altinn.no/accessmanagement/api/v1/enduser/connections/resources

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`from`	UUID	Nei	partyUuid for avsenderen
`to`	UUID	Nei	partyUuid for mottakeren
`resource`	string	Nei	Ressurs-ID

API: Fjerne ressursdelegering

Fjerner en delegert ressurs fra en tilkobling.

Test: DELETE https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections/resources
Produksjon: DELETE https://platform.altinn.no/accessmanagement/api/v1/enduser/connections/resources

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`from`	UUID	Ja	partyUuid for avsenderen
`to`	UUID	Ja	partyUuid for mottakeren
`resource`	string	Nei	Ressurs-ID

API: Hente enkeltrettigheter for en ressurs

Henter enkeltrettigheter (les, skriv, signer osv.) som er delegert for en spesifikk ressurs mellom to parter.

Test: GET https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections/resources/rights
Produksjon: GET https://platform.altinn.no/accessmanagement/api/v1/enduser/connections/resources/rights

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`from`	UUID	Ja	partyUuid for avsenderen
`to`	UUID	Ja	partyUuid for mottakeren
`resource`	string	Nei	Ressurs-ID

API: Delegere enkeltrettigheter for en ressurs

Delegerer enkeltrettigheter for en ressurs til en part.

Test: POST https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections/resources/rights
Produksjon: POST https://platform.altinn.no/accessmanagement/api/v1/enduser/connections/resources/rights

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`to`	UUID	Ja	partyUuid for mottakeren
`resource`	string	Nei	Ressurs-ID

Eksempelforespørsel (body)

{
  "directRightKeys": [
    "read",
    "write"
  ]
}

API: Oppdatere enkeltrettigheter for en ressurs

Oppdaterer (erstatter) enkeltrettigheter for en ressurs.

Test: PUT https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections/resources/rights
Produksjon: PUT https://platform.altinn.no/accessmanagement/api/v1/enduser/connections/resources/rights

Spørreparameterne og forespørselskroppen er de samme som for delegering (POST).

API: Kontrollere delegeringsmulighet for ressurs

Sjekker om den innloggede brukeren kan delegere rettigheter for en gitt ressurs.

Test: GET https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/connections/resources/delegationcheck
Produksjon: GET https://platform.altinn.no/accessmanagement/api/v1/enduser/connections/resources/delegationcheck

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`party`	UUID	Ja	partyUuid for parten
`resource`	string	Nei	Ressurs-ID

Eksempelrespons

{
  "resource": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Skattemelding",
    "refId": "skd-skattemelding"
  },
  "rights": [
    {
      "right": {
        "key": "read",
        "name": "Les",
        "action": {
          "type": "urn:oasis:names:tc:xacml:1.0:action:action-id",
          "value": "read"
        }
      },
      "result": true,
      "reasonCodes": []
    }
  ]
}

Sluttbrukerens egne klientforhold

Endepunktene nedenfor lar en innlogget person se og administrere sine egne klientforhold. Det vil si klienter som er delegert til brukeren via en tjenestetilbyder.

API: Hente mine klienter

Henter alle klienter som den innloggede brukeren har fått delegert tilgang til.

Test: GET https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/clientdelegations/my/clients
Produksjon: GET https://platform.altinn.no/accessmanagement/api/v1/enduser/clientdelegations/my/clients

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`provider`	array (UUID)	Nei	Filtrer på spesifikke tjenestetilbydere

Paginering styres med X-Page-Size og X-Page-Number i headere.

Eksempelrespons

{
  "links": {
    "next": null
  },
  "data": [
    {
      "provider": {
        "id": "4a06214d-b261-4695-b33a-0771a995b503",
        "name": "SMART REGNSKAPSBYRÅ AS",
        "type": "Organisasjon",
        "variant": "AS"
      },
      "clients": [
        {
          "client": {
            "id": "006cdf09-e874-4fcc-8502-5342b871e2ac",
            "name": "ENKEL SKJØR TIGER AS",
            "type": "Organisasjon",
            "variant": "AS"
          },
          "access": [
            {
              "role": {
                "id": "42cae370-2dc1-4fdc-9c67-c2f4b0f0f829",
                "code": "rettighetshaver",
                "urn": "urn:altinn:role:rettighetshaver"
              },
              "packages": [
                {
                  "id": "a5f7f72a-9b89-445d-85bb-06f678a3d4d1",
                  "urn": "urn:altinn:accesspackage:regnskapsforer-uten-signeringsrettighet"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

API: Fjerne klientdelegering

Fjerner en delegert klienttilgang for den innloggede brukeren.

Test: DELETE https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/clientdelegations/my/clients
Produksjon: DELETE https://platform.altinn.no/accessmanagement/api/v1/enduser/clientdelegations/my/clients

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`provider`	UUID	Ja	partyUuid for tjenestetilbyderen
`from`	UUID	Ja	partyUuid for klienten

Eksempelforespørsel (body)

{
  "values": [
    {
      "role": "rettighetshaver",
      "packages": [
        "urn:altinn:accesspackage:regnskapsforer-uten-signeringsrettighet"
      ]
    }
  ]
}

API: Hente mine tjenestetilbydere

Henter alle tjenestetilbydere som har delegert klientrettigheter til den innloggede brukeren.

Test: GET https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/clientdelegations/my/clientproviders
Produksjon: GET https://platform.altinn.no/accessmanagement/api/v1/enduser/clientdelegations/my/clientproviders

Dette endepunktet har ingen spørreparametere.

API: Fjerne tjenestetilbyder

Fjerner forholdet til en tjenestetilbyder. Dette fjerner samtidig alle klientdelegeringer fra denne tjenestetilbyderen.

Test: DELETE https://platform.tt02.altinn.no/accessmanagement/api/v1/enduser/clientdelegations/my/clientproviders
Produksjon: DELETE https://platform.altinn.no/accessmanagement/api/v1/enduser/clientdelegations/my/clientproviders

Spørreparametere

Parameter	Type	Obligatorisk	Beskrivelse
`provider`	UUID	Ja	partyUuid for tjenestetilbyderen