Skip to main content

Signature

About the MobileID signature API​

You can use our MobileID signature API as an alternative to our MobileID authentication API. Unlike the authentication operation, the signing operation also returns a signed JSON Web Token (JWT) back to you which contains all relevant transaction data. This allows you to store a third-party proof of the authentication which can be used for non-repudiation.

The MobileID signature API also allows you to use a larger data size in the pre-operation context content (content). To learn more, see Operation context maximum character length in the MobileID API reference documentation.

Which operation should I use?​

Your requirements for data size and long-term transaction proof will often determine whether you use the MobileID authentication or signing operation.

For both APIs:

  • MobileID retains transaction data for the last 60 days. You can access this data using the MobileID Get device transactions endpoint.
  • Signicat retains transaction data for the last 12 months. You can access this this data using the Audit logs service in the Signicat Dashboard. To see this, go to Signicat Dashboard > Settings > Audit logs

However, only the MobileID signature API returns a signed JWT that can be stored long-term as proof of the transaction.

How does the MobileID signature API work?​

When a signing operation is successfully completed, a signed JWT containing the transaction data is returned in the signature field of the response.

Click to see example
Example: Completed signature response
{
  "type": "SIGNATURE",
  "accountId": "a-sdge-mokc8nV8siYpbnqxyban",
  "transactionId": "033e61dc-0585-48ec-a622-194b2fdeebab",
  "state": "COMPLETED",
  "created": "2025-01-08T09:55:59.560Z",
  "completed": "2025-01-08T09:56:02.895Z",
  "device": {
    "id": "260eeae5-15b0-4c14-92e8-f85ffe67d91c",
    "state": "ACTIVE",
    ...
  },
  "user": {
    "externalRef": "nilnil-test",
    "id": "6dcb5ccd-faac-4acc-8dcc-d9a2cbe266d5",
    ...
  },
  "operationProperties": {
    "authLevel": "TWO_FACTOR",
    "authMethod": "DEVICE_PIN",
    "preOperationContext": {
      "content": "Sign this",
      "mimeType": "text/plain"
    },
    "pushSent": false,
    "location": {
      "accuracy": "1.3423532645642E13",
      ...
    },
    "geofencing": {
      "countryCode": "NO",
      ...
    },
    "sessionExpiryTime": "2025-01-08T10:00:59.607Z",
    "clientData": "",
    "signedJwtCertificateOption": "NONE"
  },
  "riskAttributes": {
    "isDebuggerConnected": "false",
    "operatingSystemType": "Android",
    ...
  },
  "signature" : "eyJ4NXQjUzI1NiI6IjMyNW ... A3dimBkXJza8jLOtC"
}

A signed JWT consists of three parts:

Want to learn more?

To learn more about JWTs, see the RFC documentation.

The JWT from the MobileID signature operation can contain the following fields in the header:

Example: MobileID signature JWT header
{
    "x5t#S256": "0456779b6966effdfc2d6d769edd3de25a7c295d27bdcc100efc8cf50f2a5372",
    "alg": "RS256",
}

Payload​

The JWT from the MobileID signature operation contains the following claims in the payload:

Example: MobileID signature JWT payload
{
    "iss": "Signicat AS",
    "transactionData": "eyJ0cmFuc2FjdGlvbklkIjoiZWUxMmEyYTktYzIzYS00NjczLWEyZjgtNDU1MzI1OTczZGNiIiwiYWNjb3VudElkIjoiYS1zZGdlLU4yN0dqUFN6WE84SkxjZjhHMUFOIiwic3RhdGUiOiJDT01QTEVURUQiLCJvcGVyYXRpb25Qcm9wZXJ0aWVzIjp7ImF1dGhMZXZlbCI6IlRXT19GQUNUT1IiLCJjb3JyZWxhdGlvbklkIjoiM2VhZTU4MzAtM2VlMi00ZTJjLWEzNGYtMTczYmRhOTg1ZDU5IiwiYXV0aE1ldGhvZCI6IkRFVklDRV9BTkRST0lEX0JJT01FVFJJQ19QUk9NUFQiLCJzZW5kUHVzaCI6ZmFsc2UsInByZU9wZXJhdGlvbkNvbnRleHQiOnsidGl0bGUiOiJDb25zZW50IFNpZ24iLCJjb250ZW50IjoibG9rbyIsIm1pbWVUeXBlIjoidGV4dC9wbGFpbiJ9LCJwdXNoU2VudCI6ZmFsc2UsInNlc3Npb25FeHBpcnlUaW1lIjoiMjAyMi0xMS0xMFQxMzozNDo0MC4wNDBaIiwic2lnbmVkSnd0Q2VydGlmaWNhdGVPcHRpb24iOiJOT05FIn0sInJpc2tBdHRyaWJ1dGVzIjp7fSwiY3JlYXRlZCI6IjIwMjItMTEtMTBUMTM6MzM6MDkuOTExWiIsImNvbXBsZXRlZCI6IjIwMjItMTEtMTBUMTM6MzM6MTYuMDM1WiIsImRldmljZSI6eyJpZCI6ImM3NDNiNTg4LWY1N2UtNGZhYy04OWMyLTZmYWMyMDU4OTc2OCIsIm5hbWUiOiJzYW1wbGVEZXZpY2UiLCJzdGF0ZSI6IkFDVElWRSIsImxhc3RPcGVyYXRpb25UeXBlIjoiU0lHTklORyIsImxhc3RVc2VkIjoiMjAyMi0xMS0xMFQxMzozMzoxNi4wMDhaIiwiY3JlYXRlZCI6IjIwMjItMTEtMTBUMTI6MDk6MDQuMDkyWiJ9LCJ1c2VyIjp7ImV4dGVybmFsUmVmIjoiZGV2NSIsImlkIjoiZTY5N2ExMzEtMGZlMy00MDgyLTljNWItOTk0MTE3MDMyOWQyIiwiY3JlYXRlZCI6IjIwMjItMTEtMTBUMTI6MDg6NTQuMjQ4WiIsImxhc3RVc2VkIjoiMjAyMi0xMS0xMFQxMzozMzoxNS45ODZaIiwic3RhdGUiOiJBQ1RJVkUifX0=",
    "sub": "e697a131-0fe3-4082-9c5b-9941170329d2",
    "iat": "1668087196",
    "jti": "ab993e6b-6788-47cb-803e-38fc5413b8ae",
}

Signature​

The signature is generated by signing the Base64-encoded header and payload with a private key, based on the algorithm specified in the header. The corresponding public key is used for validation.

Your application should always validate the signature of the signed JWT.

Want to learn more?

For general recommendations on JWT signature validation, see the RFC documentation.

How to get the public key​

The public key needed to validate a signature can be obtained by using the Get signing certificates endpoint in the Signicat MobileID Admin API.

Here, you can also also obtain previous certificates that are deactivated and any available future certificates.

Use the Signicat Dashboard

For testing and development use, you can also use the Signicat Dashboard to obtain the public key. To do this:

  1. Go to Signicat Dashboard > Products > MobileID > Details.
  2. Select the Signing certificates tab.

Cache the certificate list​

We recommend that you cache the certificate list locally, then use this cache for signature validation. This means that you do not need to get it for each signature operation.

You should refresh the cache with new data from the Get signing certificates endpoint when you see a new x5t#S256 thumbprint, or when the cache has expired.

Cache expiry

In order to pick up on any certificate deactivations, you should set the cache expiry to be reasonably short.

Key rotation​

Periodic key rotation is considered good practice, as it ensures a higher level of security. This means that the certificates that you can obtain are subject to change at any given time.

When validating a signature, you should consider the following:

  • If a signature validation fails, check if the thumbprint in the x5t#S256 matches the sha256Fingerprint of the certificate that you are using. If the thumbprint does not match, then the signing certificate may have been rotated.
  • If you are validating an older signature, then the signing may have been performed with an old certificate, found in the deactivated certificate list.
Last updated:
On this page