CertificateMetadata API

The CertificateMetadata API is an API for querying for the certificates used by communication parties in Adresseregisteret (AR).

Environments

Environment URL
Test cm.test.grunndata.nhn.no
QA cm.qa.grunndata.nhn.no
Production cm.grunndata.nhn.no

Endpoints

HTTP Method Endpoint Description
GET /CertificateMetadata Search for certificates by a range of query parameters
GET /CertificateMetadata/{thumbprint} Certificate lookup by the certificate thumbprint
POST /CertificateMetadata/update/{herId} Forces an update of the certificate metadata for the given HerId

GET /CertificateMetadata

This is an endpoint for querying the certificates, and their metadata, stored in CertificateService. Querying can be done through the use of a range of parameters described below

Query parameters

Parameter Type Description
ou string Partial organization name
ou:exact string Exact organization name
sn string Partial certificate serial number (orgnr in SEID v1 certificates)
sn:exact string Exact certificate serial number (orgnr in SEID v1 certificates)
orgnr string Exact organization number. Searches for exact organization number in both serial number (SEID v1) and organization identifier (SEID v2) fields
organizationidentifier string Partial organization identifier. It has the format NTRNO-[orgnr]. only present on SEID v2 certificates
organizationidentifier:exact string Exact organization identifier. It has the format NTRNO-[orgnr]. only present on SEID v2 certificates
validto string The certificate's expiration date. This parameter is explained further in the date parameters section
page int Number of the page of certificates. Starts on page 1
count int Number of certificates per page. Default value is 100, max value is 1000

Response

{
  "total": 0,
  "totalPages": 0,
  "currentPage": 0,
  "entries": [
    {
      "thumbprint": "string",
      "subjectOrganizationIdentifier": "string",
      "subjectSerialNumber": "string",
      "subjectCommonName": "string",
      "subjectOrganizationalUnitName": "string",
      "subjectCountryName": "string",
      "validFrom": "2023-03-31T13:26:57.849Z",
      "validTo": "2023-03-31T13:26:57.849Z",
      "usedByHerIds": [
        0
      ],
      "revoked": false
    }
  ],
  "links": [
    {
      "relation": "string",
      "uri": "string"
    }
  ]
}

Examples

Search for metadata based on ValidTo
Certificate with validto between 1990-06-26 and 2021-04-21:

GET /CertificateMetadata?ValidTo=gt1990-06-26T00:00:00&ValidTo=lt2021-04-21T00:00:00

Curl

curl -X 'GET' \
  'https://cm.grunndata.nhn.no/CertificateMetadata?ValidTo=gt1990-06-26T00:00:00&ValidTo=lt2021-04-21T00:00:00' \
  -H 'accept: application/json'

Certificate with validto at exactly 1990-06-26T00:00:00:

GET /CertificateMetadata?ValidTo=1990-06-26T00:00:00

Curl

curl -X 'GET' \
  'https://cm.grunndata.nhn.no/CertificateMetadata?ValidTo=1990-06-26T00:00:00' \
  -H 'accept: application/json'

Combined search
Certificate with lege in the organization name that expires sometime in October 2021:

GET /CertificateMetadata?Ou=lege&ValidTo=2021-10

Curl

curl -X 'GET' \
  'https://cm.grunndata.nhn.no/CertificateMetadata?Ou=lege&ValidTo=2021-10' \
  -H 'accept: application/json'

Certificate with a specific org number, expiring sometime after the start of October 1st 2021, but before the end of October 7th 2021:

GET /CertificateMetadata?Sn:exact=999999999&ValidTo=ge2021-10-01&ValidTo=le2021-10-07

Curl

curl -X 'GET' \
  'https://cm.grunndata.nhn.no/CertificateMetadata?Sn:exact=999999999&ValidTo=ge2021-10-01&ValidTo=le2021-10-07' \
  -H 'accept: application/json'

GET /CertificateMetadata/{thumbprint}

This is an endpoint for looking up a specific certificate, and its metadata, by the certificate thumbprint.

Path parameters

Parameter Type Description
thumbprint string The thumbprint of the certificate

Response

{
  "thumbprint": "string",
  "subjectOrganizationIdentifier": "string",
  "subjectSerialNumber": "string",
  "subjectCommonName": "string",
  "subjectOrganizationalUnitName": "string",
  "subjectCountryName": "string",
  "validFrom": "2023-03-31T13:51:46.804Z",
  "validTo": "2023-03-31T13:51:46.804Z",
  "usedByHerIds": [
    0
  ],
  "revoked": false
}

Example

GET /CertificateMetadata/000ec13d3c8ce3d86b773a81cb63fa0acd29c981

Curl

curl -X 'GET' \
  'https://cm.grunndata.nhn.no/CertificateMetadata/000ec13d3c8ce3d86b773a81cb63fa0acd29c981' \
  -H 'accept: application/json'

POST /CertificateMetadata/Update/{herId}

Forces an update of the CertificateMetadata for the given HerId. Since everything should stay in sync automatically, this should normally not do anything, but if things happen to be out of sync, this will reveal the problem, and sync this HerId. Returns the text CertificateMetadataWasUpdated if a sync issue was corrected, or NothingToUpdate if everything was up to date.

Path parameters

Parameter Type Description
herid int The herId of the communication party that you want to force a certificate metadata update on

Example

POST /CertificateMetadata/update/123

Curl

curl -X 'POST' \
  'https://cm.grunndata.nhn.no/CertificateMetadata/Update/123' \
  -H 'accept: application/json' \
  -d ''