Civic Developer Hub
Search…
Civic Pass
Integrations
Legacy APIs (SIP)
Step-by-step guide
Step 0: Initialize Civic client library
First of all, you must include the Civic front-end library on your front-end. This exposes a single global object, civic.
1
<link rel="stylesheet" href="https://hosted-sip.civic.com/css/civic-modal.min.css">
2
3
<script src="https://hosted-sip.civic.com/js/civic.sip.min.js"></script>
4
Copied!
Then, initialize it by passing in your application ID (for example ‘foo123’). You can find your application ID in the Application details section of your Civic Integration Portal Applications section.
1
// Instantiate instance of civic.sip
2
var civicSip = new civic.sip({
3
appId: 'ABC123',
4
// OPTIONAL configuration
5
hideIntro: false, // set to true to override intro screen (Proof of Identity only)
6
});
Copied!
Additionally a button to initiate the verification process should be added to your web page. For example, for a signup scenario, place a “Continue with Civic” button on your page (see our style guidelines for the Civic color palette and related iconography):
It is also recommended to give user’s context on the process they will need to go through. For example, if you need to verify their identity, let them know that they need to download the Civic App and have a government issued ID ready as well as be in a well lit location so that the Images they take are clear and legible.
1
<button id="signupButton" class="civic-button-a medium" type="button">
2
<span>Continue with Civic</span>
3
</button>
Copied!
Step 1: Request user data
To request data about your user, you must initialise a new scope-request from your front-end. Scope requests are objects that detail specific sets of verified data you wish returned from your user.
Create a new scope-request by calling the
signup method of the civic global object, passing in the type of scope-request to resolve.In our example, we will use the
BASIC_SIGNUP type, which requests your user’s verified email address. You can find details on all supported scope request types here.1
var button = document.querySelector('#signupButton');
2
button.addEventListener('click', function () {
3
civicSip.signup({ style: 'popup',
4
scopeRequest: civicSip.ScopeRequests.BASIC_SIGNUP });
5
});
Copied!
When calling the
signup method, the Civic front-end library opens a modal dialog displaying a Civic Wallet QR code or a button to open the Civic App if viewed on a mobile browser. This QR code/app link is generated specifically for this scope-request and can only be used once.
The QR code/app link bridges the air gap between the browser and the user’s smartphone. The user scans the QR code using the Civic Wallet app and is prompted to authorize or deny the scope request. The prompt highlights the data that is being requested and the requesting party.
MOBILE BROWSER NOTE
When using the Civic SIP flow from a mobile browser, we do not show the QR Code, but instead direct the user from the browser to the Civic App using deeplinking.
Once the user approves the scope request on the Civic App, they will be redirected back to the browser with a new tab being opened on your integrated web page. We append a query parameter called uuid to the parent URL so that we can identify the fact that this page is loading after returning from the Civic App.
Step 2: Receive JWT Token
In order to retrieve the encrypted user data, you first need the request-specific JWT Token that is generated as soon as the user authorizes the scope-request. We call this JWT token
auth-code.Your front-end has access to this token by registering an event handler for the 'auth-code-received' event. The token is available under the 'response' property:
1
civicSip.on('auth-code-received', function (event) {
2
/*event:
3
{
4
response: "The JWT Token in base64"
5
}*/
6
});
Copied!
You can find details on all events emitted by the Civic front-end library.
Step 3: Forward the token to your back-end
Now that you have the auth-token in your front-end, you must forward it to your back-end, so that it can be securely exchanged for the PII using the Civic back-end SDK. How you achieve this is up to you, but assuming you have a method
sendAuthCodetoBackEnd your event handler code will probably look very similar to this:1
civicSip.on('auth-code-received', function (event) {
2
// encoded JWT Token is sent to the server
3
var jwtToken = event.response;
4
5
// Your function to pass JWT token to your server
6
sendAuthCodeToBackEnd(jwtToken);
7
});
Copied!
Step 4: Exchange token for user data
First, create an instance of the Civic Server SDK, passing in your application ID, private signing key and secret.
Your private keys and secret should only be used on the server and never exposed on the client side.
If you are using a Node.js back-end, then you simply
npm install civic-sip-api and initialize the civic-sip-api npm package into your Node.js application with your account details:1
const civicSDK = require('civic-sip-api');
2
3
// Step 4: Initialize the instance passing your appId and secret.
4
const civicClient = civicSDK.newClient({
5
appId: 'foo123',
6
prvKey: PRIVATE_KEY,
7
appSecret: APP_SECRET,
8
});
Copied!
Once you have received the request-specific JWT token from your front-end, you can exchange it for the user data you requested.
User data is returned to your server encrypted with your secret and signed by Civic. The Civic server SDK verifies and decrypts it transparently. Also, for security reasons a JWT token can only be used once for user data exchange. If the token is exchanged and user data needs to be fetched again, a new request must be approved by the user.
1
civicClient.exchangeCode(jwtToken)
2
.then((userData) => {
3
// store and use the user data as appropriate to your system
4
/* {
5
"data": [
6
{
7
"label": "contact.personal.email",
8
"value": "[email protected]"
9
}
10
]
11
} */
12
13
}).catch((error) => {
14
console.log(error);
15
});
Copied!
Last modified 8mo ago