Iframe method

To use the iframe, use the path https://embed.okysafe.com and add identification-token in the query params.

<iframe
  src="https://embed.okysafe.com/?identification-token=IDENTIFICATION_TOKEN"
  sandbox="allow-scripts allow-top-navigation allow-forms"
/>

Identification token

The identification token is a JWT signed by the private key provided by OkySafe. It is important to set an expiry time for the token and store it until it expires.

Payload

{
  "clientPublicKey": "CLIENT_PUBLIC_KEY",
  "iframeOrigin": "https://example.com",
  "redirectAfterVerificationUrl": "https://example.com/callback",
  "isVerificationRequired": true
}

• clientPublicKey: Public key of the client provided by OkySafe.
• iframeOrigin: This is the origin URL where the iframe is to be embedded. It is important to match the protocol, the full domain and the port (if you are working on a port other than 80 or 443). Examples
• redirectAfterVerificationUrl: Redirect URL after verification.
• isVerificationRequired: If false, the responsible statement and the buttons to disable the iframe will be displayed. If true, they will not be displayed.

iframeOrigin examples

More info about origin URL 

Callback

Once the user has verified their identity, they will be redirected to the URL provided in redirectAfterVerificationUrl along with the result-token parameter (https://example.com/callback?result-token=RESULT_TOKEN). This result token is also a JWT signed by the same private key as the identification token, so that the result token can be verified as coming from OkySafe. The payload can contain the following fields:

• isVerified: A boolean indicating whether the user has been verified.
• errorCode: If there has been an unexpected error we will send a code with the error.

Events

Events are used to alert the website to actions it should take. To send events we use the postMessage() method , where the message has the following format:

{
  "code": "Code event",
  "payload": "Optional parameter that may contain relevant information."
}

To listen to the events we send, it is necessary to add the event listeners  of message type.

Code events

okysafe.page-is-ready

This event is used to notify the website that the iframe is loaded.

okysafe.age-consent-ok

This event is triggered when the user clicks on the button that assumes they are of legal age. In this way we warn the website that it should close the modal or move the user to the protected content.

okysafe.already-verified

It is possible that the user is already verified by us. In this case, we will send the event along with the payload with a nonce and a signature.

{
  "code": "okysafe.already-verified",
  "payload": {
    "nonce": "NONCE",
    "signature": "SIGNATURE"
  }
}

The signature parameter is the hexadecimal code generated by the HMAC-SHA256 algorithm with the private key. And the encrypted message is the union of the following ordered fields:

1. iframeOrigin
2. clientPublicKey
3. nonce

We will describe a function to check if the signature is valid.

iframeOrigin = 'https://example.com'
clientPublicKey = 'test123'
nonce = '1234'
 
clientSecretKey = 'secret123'

The result of the function must be:

8f2ef32fad311bfbc4ff8e4617d91d0ccdff08989678bbf5d8af2b02ffb82abc

These values can be tested to check that the implemented method and our method are the same.