Using Nametag in Tines Stories

Introduction

Tines is a security and workflow automation platform that uses a straightforward graphical design process to automate tasks.

Nametag is a modern identity platform that uses government-issued photo IDs to identify a person over the Internet, while preserving the privacy of the person.

Tines’ ability to work with APIs combined with Nametag’s modern API for identity is the simplest way to add secure identity verification to your workflows.

This article assumes you have some familiarity with Tines and no familiarity with Nametag. For a nice introduction to Tines please see the content in the Tines University.

Assembling the information from Nametag that Tines needs

You will need three things from Nametag to configure Tines: a Nametag Enviroment identifier, a Nametag webhook shared secret, and a Nametag API key.

To get those, you will need to create a Nametag instance for yourself. Make sure you have your government-issued photo ID and an Android or iOS mobile phone, then go to https://console.nametag.co/signup and follow the steps. This should take less than 5 minutes, but if you need help please reach out to us at help@nametag.co.

Once you are logged into your Nametag console, click the “Configure” button in the upper right of the screen. The Nametag console Configure button

To get:

  • the Nametag Environment identifier: click on OAuth on the right and copy the Client ID. The Nametag environment identifier
  • the webhook shared secret for your environment: click on Webhooks on the right and copy the Shared Secret The Nametag webhook shared secret
  • the API Key: click on API Keys on the right, then “Create new API key”, fill in a name and copy the API key. For now you can leave the Role as Admin and the Environment as “All environments” The API Key

In Tines, add each of those items as a Credential. For the Nametag Environment Identifier and the webhook shared secret do not enter anything in the “Domains” section of the Tines Credentials editor. For the API key, you can enter nametag.co if you want. All three credentials can be entered as “Text” credentials and will look like: Tines Credendials

At this point, you have a fully working (although time-limited; email help@nametag.co if you need your trial extended) Nametag trial environment and you have all the information you need from Nametag in your Tines environment.

Setting up Tines actions

The high-level steps that we’ll configure in Tines are:

  1. Get a link from Nametag to request information from the end-user via a REST API call
  2. Deliver that link to the end-user
  3. Wait for a webhook from Nametag
  4. Use the information in the body of the webhook and the API key to get the data the end-user shared with you

To get a sharing-request link that you can send to an end-user, you simply have to make one API call to Nametag. That API call is authenticated by the API key you created earlier, specific to the Nametag Environment you created earlier, and will request certain pieces of data (scopes) from the end-user.

Drag the “HTTP Request” action into your story from the sidebar and configure it as follows:

  • Name: RequestIDV

  • URL: https://nametag.co/api/requests

  • Content type: JSON

  • Method: POST

  • Payload:

    {
  "env": "<<CREDENTIAL.ntenv>>",
  "scopes": [
	"nt:legal_name"
  ]
}

  • Basic auth:

    • Username: x (or anything, this isn’t used)
    • Password: <<CREDENTIAL.apikey>>

Note that I named the Nametag Environment credential ntenv and the Nametag API Key apikey; if you chose something different make sure you use those values.

Clicking “< > Editor” button on the right side of the Tines workspace should show this (or something close to it):

{
  "url": "https://nametag.co/api/requests",
  "content_type": "application_json",
  "method": "post",
  "payload": {
    "env": "<<CREDENTIAL.ntenv>>",
    "scopes": [
      "nt:legal_name"
    ]
  },
  "basic_auth": [
    "x",
    "<<CREDENTIAL.apikey>>"
  ]
}

If you press the Play button on this action, you’ll see in the Events window the request was made and you got a response that looks like:

{
  "request": {
    "body": {
      "id": "f78ee334-79a8-4a5e-be4a-d728e226df64",
      "status": 100,
      "env": "2zna1cddrxq9vue",
      "scopes": [
        "nt:legal_name"
      ],
      "template": "",
      "link": "https://nametag.co/x/acme/mykgjyonberdez",
      "phone": "",
      "label": ""
    },
    "headers": {},
    "status": 200
  }
}

The id, env, and link fields will be different for you, of course. The important thing is that there is a link returned; this is what you will need to deliver to your end-user.

If you have been a Tines developer, you certainly have used many methods to deliver data to your end-users. Any of those will work for delivering this link—you can even set a redirect to it and open it for the end-user from within your Tines story.

Because Tines’ email delivery tool is so simple to use, that is what I’ll use.

The first thing we need to do is get an email address from the user of the Tines story, which is easily done with a Tines web page that has a form element for entering the email address.

Create a web page by clicking the “+ / Tools” on the left of your Tines workspace, then drag the “Page” object onto your workspace. Name the page “Request identity verification” and then edit the page text with instructions and add an email input field. Mine looks like:

Then add a success message in the page configuration on the right of the Tines workspace, my message is:

A request verification email has been sent to
<<request_identity_verification.body.email>>; please wait for them to
complete the verification, at which point the webhook action will run
and you will see the results in the page titled Results of Identity
Verification

Now that you have a form to collect an email address we can use the Tines “Send Email” action. Drag that action from the left into your workspace and configure it to send an email to the address entered in the form by setting these fields:

  • Recipients: choose List and <<request_identity_verification.body.email>> as the address. (If you named your page something other than “Request identity verification” you’ll have to make that change here, too.)
  • Reply to: an address end-users can reply to and ask for help
  • Sender name: the friendly name that will be associated with the email
  • Subject: the subject for your emails; something like “Verification from MyCompany”
  • Body: the text of the email that explains to the recipient what this is for. The link should be included somewhere in this email using the Tines variable <<request.body.link>>

Connect the “Request identity verification” page to the “Request” action, then connect the “Request action” to the “Send email with request” action. Mine looks like this: Tines configuration for request creation and sending

To try it, open the web page, enter your email address, then check that you got the email with the link. You can continue on to verify your identity; Tines won’t know about it yet but you can see it in the Nametag console: on the Verifications page change the “Requested by” dropdown to either “All team members” or “Created by API” to see the request, it will look like this: Nametag console with “Created by API” selected

Retrieving shared information from Nametag

After the end-user has shared information with you via Nametag, you need to get notified that that process is complete and then retrieve the data.

There are several approaches to this, but I’ll describe using webhooks to do this.

Receiving Nametag data in Tines via a webhook

Nametag can POST a cryptographically signed message to a pre-defined HTTP endpoint when an end-user shares data with you (and in some other circumstances, but what we care about for this example is when the data is shared). This is configured in both Nametag and Tines using webhooks.

The steps go between the configuration pages in the two platforms as we build the connection between Nametag and Tines.

Receiving Nametag data in Tines via a webhook

Nametag can POST a cryptographically signed message to a pre-defined HTTP endpoint when an end-user shares data with you (and in some other circumstances, but what we care about for this example is when the data is shared). This is configured in both Nametag and Tines using their respective webhook configurations.

The following steps go between the configuration pages in the two platforms as we build the connection between Nametag and Tines.

Starting in Tines, drag a Tines Webhook Action into your workspace and click on it to edit it. Change the “Allowed verbs” to just post, then click the “copy” button next to the “Webhook URL” to copy it.

Now go to the Nametag console and click “Configure” in the top right, then click “Webhooks” on the left. Click “Add a webhook”, paste the URL you copied in Tines into the “Delivery URL” field and press “Save”. Then toggle on “Enabled” and, under “Events”, “Data is shared with you”. When that is complete, copy the “Shared Secret” by pressing the “Copy” button next to it.

Going back to Tines, add this shared secret to the credentials in your Tines story if you didn’t do it earlier. Then create a Trigger Action by dragging it from the left into your story workspace; we will use this Trigger Action to validate the webhook using the shared secret. Edit the rule to compare <<webhook_action.headers.x_nametag_signature>> (or, in the pretty-printed version, {}webhook_action.headers.x_nametag_signature) to <<HMAC_SHA256(JSON(webhook_action.body),CREDENTIAL.webhook_secret)>> (or, in the pretty-printed version, {}HMAC_SHA256(JSON(webhook.action.body),CREDENTIAL.webhook_secret)). In the “Editor” view, the JSON for this looks like

{
  "rules": [
    {
      "type": "field==value",
      "value": "<<HMAC_SHA256(JSON(webhook_action.body),CREDENTIAL.webhook_secret)>>",
      "path": "<<webhook_action.headers.x_nametag_signature>>"
    }
  ]
}

At this point Nametag is configured to send webhooks to Tines when someone shares data with you (via your Nametag environment) and Tines is configured to receive and validate the webhooks that Nametag sends.

Using the data from the webhook to retrieve shared information

The webhook body is JSON that looks like

{
  "event_type": "share",
  "subject": "SUBJECT",
  "request": "REQUEST_ID",
  "scopes": ["SCOPE", ...]
}

where the REQUEST_ID in the request field is the same as the ID returned when you created the request (request.body.id)

Once you know that you have a valid webhook message, you should then compare the ID of the request created to the value in the webhook to ensure you are working with the same request. This can be done with a Tines Trigger Action represented by this JSON:

{
  "rules": [
    {
      "type": "field==value",
      "value": "<<verify_webhook_security.request>>",
      "path": "<<request.body.id>>"
    }
  ]
}

The scopes field lists what type of data you are authorized to retrieve; in most cases this will be what you asked for in the request and also what you’ll retrieve.

The most important thing in the webhook body is the subject; this is the unique representation of the person who shared data with you and is specific to your Nametag environment. This piece of data does not contain any PII and can be safely stored without encryption. In combination with a Nametag API key and the end-user’s permission you can retrieve the data the end-user shared with you at any time before your access to the data expires.

Now that you have the subject and the scopes from the webhook and you’ve confirmed the data is from Nametag and unaltered, using your API key you can retrieve the information that you requested from the end-user. This uses another HTTP Request object with these settings:

  • URL: https://nametag.co/people/<<webhook_action.body.subject>>/properties/<<JOIN(webhook_action.body.scopes, ",")>>
  • Content type: JSON
  • Method: GET and the Basic Auth settings:
  • Username: x (this isn’t used and can be anything
  • Password: <<CREDENTIAL.apikey>>

or, in the “< > Editor” view:

{
  "url": "https://nametag.co/people/<<webhook_action.body.subject>>/properties/<<JOIN(webhook_action.body.scopes, \",\")>>",
  "content_type": "application_json",
  "method": "get",
  "basic_auth": [
    "",
    "<<CREDENTIAL.apikey>>"
  ]
}

That will generate a reponse from Nametag that has the format

{
  "subject": "uqconnftqow7ntkwngxpsm3eb4@2zna1cddrxq9vue.nametag.co",
  "requests": [
    {
      "id": "72f69432-8fe4-46a8-b90d-9a023c23c26c",
      "created_at": "2024-03-01T21:24:37.417703Z",
      "status": 200,
      "scopes": [
        "nt:legal_name"
      ]
    }
  ],
  "properties": [
    {
      "expires": "2024-03-04T21:24:58Z",
      "scope": "nt:legal_name",
      "value": "The Person's Legal Name",
      "status": 200
    }
  ]
}

and, in the properties section, you can see the person’s legal name as taken from their government-issued photo ID.

Using the information from Nametag

Now that you have the data from Nametag you can use it for many things:

  • looking up that person in your directory to change their password using another Tines story, since you now know the person you are dealing with is, in fact, the person with that name
  • combining the legal name with other information from other Tines stories to create or update an account
  • authorize access to another Tines story based on the proof of identity that Nametag offers
  • sharing that information with a help-desk employee so they are certain of the identity of the person with whom they are communicating

Really, any place in Tines you need to have the confirmed identity of a person is a place where you integrate Nametag.

Because this is just an example, the last thing we’ll do is display the legal name on a webpage. Drag another “Page” object from the “Tools” menu onto your Tines workspace and make these settings:

  • Page behavior: Show success message
  • Success message: Hello <<http_request_action.body.properties[0].value>>
  • Submit automatically: On

Summary

At the end of these steps, you will have a Tines story board that looks like: The completed Tines storyboard showing the integration with Nametag

and the ability to securely request validated identity information from your employees, customers, or anyone else you interact with.

Other resources

Nametag can be used in many ways for many purposes; visit our website for more use cases and examples: https://getnametag.com

The Nametag API is documented at https://getnametag.com/docs/api

The Nametag console is explained at https://getnametag.com/help/getting-started

And, of course, we are always happy to help you! Send us email at help@nametag.co.