Service Registry API Specification

Authorization

The service registry API uses OAuth2 for authorization and expects self-contained JWTs from Maskinporten. The JWT token requests to Maskinporten are expected to contain x5c for the Norwegian business certificate (SEIDv1 or SEIDv2) the token request was signed with.

Maskinporten (external link)

eFormidling creates OAuth clients in Maskinporten as part of the onboarding process:

The Client ID is MOVE_IP_<orgnumber>
One or more of the following scopes are granted to the client:
- move/dpo.read (eFormidlings meldingstjeneste)
- move/dpe.read (eInnsyns meldingstjeneste)
- move/dpi.read (Digital Post til Innbyggere)
- move/dpf.read (KS SvarUt og SvarInn)
- move/dpv.read (Altinn Digital Post)

The services

HTTP Method	URL	Description	Media type(s)
GET	/identifier/{identifier}	Lookup all service records	application/json, application/jose
GET	/identifier/{identifier}/process/{processIdentifier}	Lookup by process	application/json, application/jose
GET	/info/{identifier}	Lookup info records	application/json, application/jose

HTTP Method

URL

Description

Media type(s)

GET

/identifier/{identifier}

Lookup all service records

application/json, application/jose

GET

/identifier/{identifier}/process/{processIdentifier}

Lookup by process

application/json, application/jose

GET

/info/{identifier}

Lookup info records

application/json, application/jose

Service Records

Lookup all service records

The service is used to get the info record, and all possible service records for the specified identifier

Organization

/identifier/{identifier}
Parameter	Description
`identifier`	Organization number, or personal identification number

Request parameters
Parameter	Description
`securityLevel`	Security level. Only applies to receivers on the KS Fiks platform. Default is highest available for receiver.
`conversationId`	Conversation ID for the request. Used for logging purposes.

Headers
Name	Description
`Authorization`	Bearer <JWT>

Curl

$ curl 'http://localhost:8080/identifier/123123123' -i -X GET \
    -H 'Accept: application/json'

Request

GET /identifier/123123123 HTTP/1.1
Accept: application/json
Host: localhost:8080

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1724

{
  "infoRecord" : {
    "identifier" : "123123123",
    "organizationName" : "foo",
    "postadresse" : {
      "adresse" : "Skrivarvegen 42",
      "postnummer" : "1337",
      "poststed" : "teststed",
      "land" : "testland"
    },
    "entityType" : {
      "name" : "ORGL"
    }
  },
  "serviceRecords" : [ {
    "organisationNumber" : "123123123",
    "pemCertificate" : "-----BEGIN CERTIFICATE-----\npem123\n-----END CERTIFICATE-----\n",
    "process" : "urn:no:difi:profile:arkivmelding:administrasjon:ver1.0",
    "documentTypes" : [ "urn:no:difi:arkivmelding:xsd::arkivmelding" ],
    "service" : {
      "identifier" : "DPO",
      "endpointUrl" : "http://endpoint.here",
      "serviceCode" : "4192",
      "serviceEditionCode" : "270815",
      "securityLevel" : null
    }
  }, {
    "organisationNumber" : "123123123",
    "pemCertificate" : null,
    "process" : "urn:no:difi:profile:arkivmelding:tekniskeTjenester:ver1.0",
    "documentTypes" : [ "urn:no:difi:profile:arkivmelding:tekniskeTjenester:ver1.0" ],
    "service" : {
      "identifier" : "DPV",
      "endpointUrl" : "http://endpoint.here",
      "serviceCode" : "4255",
      "serviceEditionCode" : "9",
      "securityLevel" : null
    }
  }, {
    "organisationNumber" : "123123123",
    "pemCertificate" : "-----BEGIN CERTIFICATE-----\npem567\n-----END CERTIFICATE-----\n",
    "process" : "urn:no:difi:profile:einnsyn:innsynskrav:ver1.0",
    "documentTypes" : [ "urn:no:difi:einnsyn:xsd::innsynskrav" ],
    "service" : {
      "identifier" : "DPE",
      "endpointUrl" : "innsyn",
      "serviceCode" : null,
      "serviceEditionCode" : null,
      "securityLevel" : null
    }
  } ]
}

Person

/identifier/{identifier}
Parameter	Description
`identifier`	Organization number, or personal identification number

Request parameters
Parameter	Description
`securityLevel`	Security level. Only applies to receivers on the KS Fiks platform. Default is highest available for receiver.
`conversationId`	Conversation ID for the request. Used for logging purposes.

Headers
Name	Description
`Authorization`	Bearer <JWT>

Curl

$ curl 'http://localhost:8080/identifier/12345678901' -i -X GET \
    -H 'Accept: application/json'

Request

GET /identifier/12345678901 HTTP/1.1
Accept: application/json
Host: localhost:8080

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1245

{
  "infoRecord" : {
    "identifier" : "12345678901",
    "entityType" : {
      "name" : "citizen"
    }
  },
  "serviceRecords" : [ {
    "organisationNumber" : "12345678901",
    "pemCertificate" : "-----BEGIN CERTIFICATE-----\ncert123\n-----END CERTIFICATE-----\n",
    "process" : "urn:no:difi:profile:digitalpost:info:ver1.0",
    "documentTypes" : [ "urn:no:difi:digitalpost:xsd:digital::digital", "urn:no:difi:digitalpost:xsd:fysisk::print" ],
    "service" : {
      "identifier" : "DPI",
      "endpointUrl" : "http://dpi.endpoint.here",
      "serviceCode" : null,
      "serviceEditionCode" : null,
      "securityLevel" : null
    },
    "orgnrPostkasse" : "post123",
    "postkasseAdresse" : "adr123",
    "mobilnummer" : "123",
    "kanVarsles" : true,
    "epostAdresse" : "post@post.foo",
    "fysiskPost" : false,
    "postAddress" : {
      "name" : "Address name",
      "street" : "Street x",
      "postalCode" : "Postal code",
      "postalArea" : "Area",
      "country" : "Country"
    },
    "returnAddress" : {
      "name" : "Address name",
      "street" : "Street x",
      "postalCode" : "Postal code",
      "postalArea" : "Area",
      "country" : "Country"
    }
  } ]
}

Errors

Identifier not found

Curl

$ curl 'http://localhost:8080/identifier/404040404' -i -X GET \
    -H 'Accept: application/json'

Request

GET /identifier/404040404 HTTP/1.1
Accept: application/json
Host: localhost:8080

Response

HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Length: 99
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

{
  "error_code" : "",
  "error_description" : "Entity with identifier '404040404' not found."
}

Receiver does not have given security level

This only applies to receivers on the KS Fiks platform. https://ks-no.github.io/fiks-platform/

Curl

$ curl 'http://localhost:8080/identifier/321321321?securityLevel=4' -i -X GET \
    -H 'Accept: application/json'

Request

GET /identifier/321321321?securityLevel=4 HTTP/1.1
Accept: application/json
Host: localhost:8080

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 78
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

{
  "error_code" : "",
  "error_description" : "security level not found"
}

Lookup by process

One may lookup a single service record by its given process. A list of valid processes can be found here: https://difi.github.io/felleslosninger/eformidling_nm_message.html

Arkivmelding

/identifier/{identifier}/process/{processIdentifier}
Parameter	Description
`identifier`	Organization number, or personal identification number
`processIdentifier`	Process identifier

Request parameters
Parameter	Description
`securityLevel`	Security level. Only applies to receivers on the KS Fiks platform. Default is highest available for receiver.
`conversationId`	Conversation ID for the request. Used for logging purposes.

Headers
Name	Description
`Authorization`	Bearer <JWT>

Curl

$ curl 'http://localhost:8080/identifier/123123123/process/urn:no:difi:profile:arkivmelding:administrasjon:ver1.0' -i -X GET \
    -H 'Accept: application/json'

Request

GET /identifier/123123123/process/urn:no:difi:profile:arkivmelding:administrasjon:ver1.0 HTTP/1.1
Accept: application/json
Host: localhost:8080

Response

HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 823

{
  "infoRecord" : {
    "identifier" : "123123123",
    "organizationName" : "foo",
    "postadresse" : {
      "adresse" : "Skrivarvegen 42",
      "postnummer" : "1337",
      "poststed" : "teststed",
      "land" : "testland"
    },
    "entityType" : {
      "name" : "ORGL"
    }
  },
  "serviceRecords" : [ {
    "organisationNumber" : "123123123",
    "pemCertificate" : "-----BEGIN CERTIFICATE-----\npem123\n-----END CERTIFICATE-----\n",
    "process" : "urn:no:difi:profile:arkivmelding:administrasjon:ver1.0",
    "documentTypes" : [ "urn:no:difi:arkivmelding:xsd::arkivmelding" ],
    "service" : {
      "identifier" : "DPO",
      "endpointUrl" : "http://endpoint.here",
      "serviceCode" : "4192",
      "serviceEditionCode" : "270815",
      "securityLevel" : null
    }
  } ]
}

eInnsyn

/identifier/{identifier}/process/{processIdentifier}
Parameter	Description
`identifier`	Organization number, or personal identification number
`processIdentifier`	Process identifier

Request parameters
Parameter	Description
`securityLevel`	Security level. Only applies to receivers on the KS Fiks platform. Default is highest available for receiver.
`conversationId`	Conversation ID for the request. Used for logging purposes.

Headers
Name	Description
`Authorization`	Bearer <JWT>

Curl

$ curl 'http://localhost:8080/identifier/123123123/process/urn:no:difi:profile:einnsyn:innsynskrav:ver1.0' -i -X GET \
    -H 'Accept: application/json'

Request

GET /identifier/123123123/process/urn:no:difi:profile:einnsyn:innsynskrav:ver1.0 HTTP/1.1
Accept: application/json
Host: localhost:8080

Response

HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 789

{
  "infoRecord" : {
    "identifier" : "123123123",
    "organizationName" : "foo",
    "postadresse" : {
      "adresse" : "Skrivarvegen 42",
      "postnummer" : "1337",
      "poststed" : "teststed",
      "land" : "testland"
    },
    "entityType" : {
      "name" : "ORGL"
    }
  },
  "serviceRecords" : [ {
    "organisationNumber" : "123123123",
    "pemCertificate" : "-----BEGIN CERTIFICATE-----\npem567\n-----END CERTIFICATE-----\n",
    "process" : "urn:no:difi:profile:einnsyn:innsynskrav:ver1.0",
    "documentTypes" : [ "urn:no:difi:einnsyn:xsd::innsynskrav" ],
    "service" : {
      "identifier" : "DPE",
      "endpointUrl" : "innsyn",
      "serviceCode" : null,
      "serviceEditionCode" : null,
      "securityLevel" : null
    }
  } ]
}

Digital post

/identifier/{identifier}/process/{processIdentifier}
Parameter	Description
`identifier`	Organization number, or personal identification number
`processIdentifier`	Process identifier

Request parameters
Parameter	Description
`securityLevel`	Security level. Only applies to receivers on the KS Fiks platform. Default is highest available for receiver.
`conversationId`	Conversation ID for the request. Used for logging purposes.

Headers
Name	Description
`Authorization`	Bearer <JWT>

Curl

$ curl 'http://localhost:8080/identifier/12345678901/process/urn:no:difi:profile:digitalpost:info:ver1.0' -i -X GET \
    -H 'Accept: application/json'

Request

GET /identifier/12345678901/process/urn:no:difi:profile:digitalpost:info:ver1.0 HTTP/1.1
Accept: application/json
Host: localhost:8080

Response

HTTP/1.1 200 OK
Content-Disposition: inline;filename=f.txt
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 1245

{
  "infoRecord" : {
    "identifier" : "12345678901",
    "entityType" : {
      "name" : "citizen"
    }
  },
  "serviceRecords" : [ {
    "organisationNumber" : "12345678901",
    "pemCertificate" : "-----BEGIN CERTIFICATE-----\ncert123\n-----END CERTIFICATE-----\n",
    "process" : "urn:no:difi:profile:digitalpost:info:ver1.0",
    "documentTypes" : [ "urn:no:difi:digitalpost:xsd:digital::digital", "urn:no:difi:digitalpost:xsd:fysisk::print" ],
    "service" : {
      "identifier" : "DPI",
      "endpointUrl" : "http://dpi.endpoint.here",
      "serviceCode" : null,
      "serviceEditionCode" : null,
      "securityLevel" : null
    },
    "orgnrPostkasse" : "post123",
    "postkasseAdresse" : "adr123",
    "mobilnummer" : "123",
    "kanVarsles" : true,
    "epostAdresse" : "post@post.foo",
    "fysiskPost" : false,
    "postAddress" : {
      "name" : "Address name",
      "street" : "Street x",
      "postalCode" : "Postal code",
      "postalArea" : "Area",
      "country" : "Country"
    },
    "returnAddress" : {
      "name" : "Address name",
      "street" : "Street x",
      "postalCode" : "Postal code",
      "postalArea" : "Area",
      "country" : "Country"
    }
  } ]
}

Lookup info records

Organization

/info/{identifier}
Parameter	Description
`identifier`	Organization number, or personal identification number

Headers
Name	Description
`Authorization`	Bearer <JWT>

Curl

$ curl 'http://localhost:8080/info/123123123' -i -X GET \
    -H 'Accept: application/json'

Request

GET /info/123123123 HTTP/1.1
Accept: application/json
Host: localhost:8080

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 332

{
  "infoRecord" : {
    "identifier" : "123123123",
    "organizationName" : "foo",
    "postadresse" : {
      "adresse" : "Skrivarvegen 42",
      "postnummer" : "1337",
      "poststed" : "teststed",
      "land" : "testland"
    },
    "entityType" : {
      "name" : "ORGL"
    }
  },
  "serviceRecords" : [ ]
}

Person

/info/{identifier}
Parameter	Description
`identifier`	Organization number, or personal identification number

Headers
Name	Description
`Authorization`	Bearer <JWT>

Curl

$ curl 'http://localhost:8080/info/12345678901' -i -X GET \
    -H 'Accept: application/json'

Request

GET /info/12345678901 HTTP/1.1
Accept: application/json
Host: localhost:8080

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 146

{
  "infoRecord" : {
    "identifier" : "12345678901",
    "entityType" : {
      "name" : "citizen"
    }
  },
  "serviceRecords" : [ ]
}