API Reference

Overview

The Nametag API contains several parts:

  • Request - get people’s consent to share data with you, to log in to your site, or to execute a transaction. (based on OAuth 2.0)
  • People - fetch and manage the data that people have shared with you.
  • Configuration - manage the configuration of your organization.

Scopes

Scopes are used to describe the information you want people to share with you. In order to request a scope you must first define it in your environment and provide additional parameters, such as what type of data and how long you need the data. This is done separately for each environment you manage in the developer console.

The following scopes are defined:

Scope Type Description
nt:name string The person’s preferred name 1
nt:first_name string The person’s preferred given (first) name 2
nt:last_name string The person’s preferred family (last) name 2
nt:phone string Phone number, in E.164 format, e.g +1 202 555-1212
nt:email string Verified email address
nt:address string Verified postal address
nt:legal_name string The person’s name from their identity document
nt:legal_first_name string The given name (first name) from their identity document 2
nt:legal_last_name string The family name (last name) from their identity document 2
nt:birth_date RFC 3339 full-date The person’s date of birth
nt:govtid_details GovtidDetailsValue Details about the person’s identity document
nt:age_over_21 boolean true if the person is over 21 years old, otherwise false
nt:age_over_18 boolean true if the person is over 18 years old, otherwise false
nt:profile_picture URL A URL to the person’s preferred profile picture. Nametag checks that the image provided is the same person as pictured on their identity document.

Subject

A subject uniquely identifies a person. We recommend that you store this field in your database when identifying a person. (In fact, this may be the only thing you need to store in your database.)

Subjects are stable within an environment. This means that even if someone revokes access to your environment and then re-grants it, or if they delete and re-install the Nametag app, the subject will remain unchanged.

Because each environment is its own privacy domain, different environments will be issued with different subjects for the same person.

Environments

Each user of the Nametag API creates one or more environments which are the basic unit of privacy separation. This means that anything a person shares with an environment is kept private from another. My default you will have one environment called “Live” for your production use and another called “Sandbox” for development, but you can have as many or as few environments as you like.

Organizations

Organizations are the unit of access control for you and your colleagues. Each Organization contains one or more Environments. Each organization has members (your colleagues) and can be assigned to roles (administrator, or read-only access).

Basics

The Nametag API is located at https://nametag.co. All requests must be made via HTTPS. Unless otherwise noted, all requests and responses are JSON-encoded and use the application/json content type.

Authentication

How you authenticate to the Nametag API varies based on the context. The following authentication methods are available:

API Key

API keys are used to manage organizations and environments. Get an API key from the developer console. Each API key is scoped to either work for some or all of your environments, depending on your needs.

To use an API key, use HTTP basic authentication with an empty username and the API_KEY as the password, or supply an API_KEY using the token query parameter.

# list all my environments
$ curl -u ":API_KEY" https://nametag.co/api/envs

# fetch information about a person (can use either a global API key, or an environment-scoped API key)
$ curl https://nametag.co/people/SUBJECT/nt:name,nt:age_over_21?token=API_KEY

ID Token

An ID token authenticates a particular person, rather than your entire environment. This is returned from the token endpoint. You can use ID tokens to fetch information about a single user only, and you must use the URL /people/me/.... To use an ID token, use HTTP basic authentication with an empty username and the ID_TOKEN as the password.

# get the current user's name
$ curl -u ":ID_TOKEN" https://nametag.co/people/me/nt:name

Response Codes

When a call succeeds the Nametag API responds with HTTP a 2xx status code:

  • 200 Ok - when data is being returned.
  • 204 No Content - when there is no response data.

In the case of errors, the server responds with the following status codes:

  • 400 Bad Request - The request is malformed.
  • 401 Unauthorized - The request lacks the required authentication credentials.
  • 403 Forbidden - The credentials provided do not permit the requested action.
  • 429 Too Many Requests - A rate limit has been exceeded.
  • 500 Internal Server Error - Something went wrong on our end.

Rate limits

Responses from the API contain several headers to provide feedback on our rate limiters. The rate limiter defines a maximum number of requests allowed in a particular time window. The number of requests and the time window may vary according to the particular route and access pattern. Each request will include the following response headers:

  • X-RateLimit-Limit - the total number of requests allowed in the current time window.
  • X-RateLimit-Remaining - the number of requests remaining in the current time window.
  • X-RateLimit-Reset - the time when the current time window will reset, in RFC 3339 full-date format.

If the rate limit is exceeded the Nametag API responds with status code 429 Too Many Requests and the standard Retry-After header which is the number of seconds to wait before retrying the request.

Request API

The request API is how you request proof of identity or personal information from people. This API implements and extends OAuth 2.0, so many standard OAuth 2.0 libraries will work with this interface.

Request authorization

If your user has an active web session, or is active in your mobile app, direct their browser to the /authorize endpoint. (If you do not have a web session or active mobile app at the time you are making a request, use the create request endpoint instead.)

Method: GET

URL: https://nametag.co/authorize

Authentication: none

Query parameters:

Parameter Description
client_id Your environment’s ID, from the developer console.
redirect_uri A URL that you control where the user will be directed when the authorization completes. This must be one of the values listed in the callback_urls list.
scope A space-separated list of the scopes you are requesting
template The name of a pre-configured template to specify additional parameters for this request. (Specify this or scope, but not both)
state (recommended) Arbitrary data that you provide which will be passed back to the REDIRECT-URI.
response_mode (optional) Determines how authorization is passed back to your app. Either query (the default) or fragment. When you pass query to response_mode the code is passed in the URL query string, e.g. https://example.com/callback?code=CODE&state=STATE. With fragment the response is passed after a hash, e.g. https://example.com/callback#code=CODE&state=STATE.
email_hint (optional) The user’s email address, if you already know it.

Example: (whitespace added for clarity)

https://nametag.co/authorize?
  client_id=obo0jukwhhlbo8&
  scope=nt%3Aemail+nt%3Aname+nt%3Alegal_name&
  state=83f4e159-5cab-4002-ac5a-809f21925a67&
  redirect_uri=https%3A%2F%2Fexample.com%2Fcallback

Authorization requests are valid for 168 hours (7 days) from their creation.

Completing authorization

When the user completes authorization, they will be redirected to your REDIRECT-URI. This URL is invoked with the following query parameters:

Parameter Description
state The arbitrary data you provided to /authorize.
code A code which you can use with the /token endpoint to exchange for information about the person.
error A text description of an error that occurred during the process. Present only if code is not present.

Example: (whitespace added for clarity)

https://example.com/callack?
  state=83f4e159-5cab-4002-ac5a-809f21925a67&
  code=09965885d2d8559d61b520935da550f7

Token endpoint

This endpoint is defined by the OAuth 2.0 specification. It allows you to exchange the code you received at your redirect_uri for an id token and a subject which uniquely identifies the person that has accepted your sharing request.

Method: POST

URL: https://nametag.co/token

Authentication: Either specify ENV-ID and API-KEY in the body of the message, or specify the API key as the password for HTTP basic authentication.

Request: An HTML form with the following parameters

Parameter Description
grant_type must be authorization_code
client_id Your environment’s ENV-ID. (optional if basic authentication is used)
client_secret A global or environment-scoped API-KEY. (optional if basic authentication is used)
redirect_uri The redirect URI passed to /authorize.
code The code you received from the user’s request to your redirect_uri.

Response: A JSON object with the following fields:

Field Meaning
id_token This token identifies the user. It is suitable for use as e.g. a session cookie. Use it to authenticate to the /people/me API to gather information about the specific user indentified in id_token. It is safe to deliver to the user’s browser.
scope A space-separated list of the scopes returned.
expires_in The number of seconds that the authorization is valid for.
subject This value uniquely identifies the person in your environment. This is a good candidate for storing in a database to track a particular user. A subject issued to one environment has no meaning to any other environment.

Example: (whitespace added for clarity)

Request:

$ curl https://nametag.co/token \
   -d grant_type=authorization_code \
   -d client_id=obo0jukwhhlbo8 \
   -d client_secret=ef5f848e265eb423ee358cf12c5aef924c20d19356f7ad5aa07ad1614cfc4411 \
   -d code=09965885d2d8559d61b520935da550f7 \
   -d redirect_uri="https://example.com/callback"

Response:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvYXQiLCJleHAiOjE2MzcyMzg3MjUsImlhdCI6MTYzNzIzNTEyNSwiaXNzIjoibmFtZXRhZy5jbyIsIm5iZiI6MTYzNzIzNTEyNSwic3ViIjoidmtsamlwa2FpbzJhcDY2M2RvNTRyNWZwMmFANWxzcWZnMWx1cXpiOXMubmFtZXRhZy5jbyJ9.U2YAAc0TMnSJD_zKcCs_9Nayhrm5OdlcsjOQwbDSjOrBlAKI5uRCqXOoBB_oGjQjmWNYZhCYMUJShBPzSZfZZQ",
  "refresh_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvcnQiLCJleHAiOjIxNDc0ODM2NDcsImlhdCI6MTYzNzIzNTEyNSwiaXNzIjoibmFtZXRhZy5jbyIsIm5iZiI6MTYzNzIzNTEyNSwic3ViIjoidmtsamlwa2FpbzJhcDY2M2RvNTRyNWZwMmFANWxzcWZnMWx1cXpiOXMubmFtZXRhZy5jbyJ9.5D8lexomXYJoGZNDUFmxNB3TnQIhSDleb7kTL89VLHX30bilq95PDyJ5vE3W1IdmWGxziK9IE4puIkXxBEj7LA",
  "id_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvaXQiLCJleHAiOjIxNDc0ODM2NDcsImlhdCI6MTYzNzIzNTEyNSwiaXNzIjoibmFtZXRhZy5jbyIsIm5iZiI6MTYzNzIzNTEyNSwic3ViIjoidmtsamlwa2FpbzJhcDY2M2RvNTRyNWZwMmFANWxzcWZnMWx1cXpiOXMubmFtZXRhZy5jbyJ9.P-elo7PUVC9dIBSV_UgoFbaHc2yATNOj8jumVTF_3izs9QqZ4lslvUsfCnogc1l7oEpowCR9d2j42J6J-5LWjw",
  "scope": "nt:email nt:name nt:legal_name",
  "expires_in": 3600,
  "token_type": "Bearer",
  "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co"
}

Create a request

Creates a new request for information from a person.

This is useful when requesting information from people over the phone, in-person, or via email. If you are integrating Nametag with a web or mobile app, you may wish to use the OAuth 2.0 authorize endpoint instead.

This API returns an identifier that can be used to track the request. It also returns a link suitable for passing to a user. Clicking this link opens the Nametag app (or app clip on iOS, or instant app on Android) and allow the user to complete the request.

If you include the optional phone parameter, then this link is sent to the user via SMS.

Requests are valid for 168 hours (7 days) from their creation.

Method: POST

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

Authentication: API key

Request: A JSON object with the following fields:

Field Type Meaning
env string The ID of the Environment associated with the request
scopes list of string A list of scopes to request
template string The ID of a pre-configured Template to use for this request (specify this or scopes, but not both)
phone string (optional) A phone number that will receive an authorization link via SMS; only available with certain plans
whatsapp string (optional) A phone number that will receive an authorization link via Whatapp; only available with certain plans
label string (optional) A internal label for the request; only available with certain plans

Response: A JSON object with the following fields:

Field Type Meaning
id string A unique identifier for this request
created_at RFC 3339 full-date Timestamp of when this request was created
updated_at RFC 3339 full-date Timestamp of the last time this request was updated
expires_at RFC 3339 full-date Timestamp of when this request expires
status number The status code for the request. Always 100 (request pending) when the request is initially created.
scopes list of string A of the scopes that were requested.
link string An authorization link. Passing this link to the user will prompt them to complete the request.
label string The label for the request; only available with certain plans

Example:

$ curl -u :$APIKEY \
  -X POST \
  https://nametag.co/api/requests \
  -d '{
    "env": "tp7975e07n8sjl",
    "scopes": ["nt:phone", "nt:legal_name"],
    "phone": "+12025551212",
    "label": "Ref Customer #41471"
}'
{
  "id": "32478070-6fc9-4b26-8f2c-5269f1222c6f",
  "status": 100,
  "scopes": ["nt:phone", "nt:legal_name"],
  "label": "Ref Customer #41471",
  "link": "https://nametag.co/i/utl2ffahuw7lqf"
}

Get a request

Fetch the status of a request.

You can also configure a webhook to receive notification when a request completes.

Method: GET

URL: https://nametag.co/api/requests/REQUEST-ID

Authentication: API key

Response: A JSON object with the following fields:

Field Type Meaning
id string A unique identifier for this request
created_at RFC 3339 full-date Timestamp of when this request was created
updated_at RFC 3339 full-date Timestamp of the last time this request was updated
expires_at RFC 3339 full-date Timestamp of when this request expires
status number The status code for the request. The value of 100 (the request is pending), 200 (the request has been accepted), 403 (the request was rejected), or 410 (the request has expired)
scopes list of string An array of the scopes that were requested
link string An authorization link. Pass this link to the user to prompt them to authorize the request.
subject string (optional) The subject of the request. Present only when status is 200. Use this as a parameter to the properties endpoint to fetch the data shared.
label string (optional) The label for the request; can be empty

Example:

When the request is complete:

$ curl -u :$APIKEY \
  -X GET \
  https://nametag.co/api/requests/32478070-6fc9-4b26-8f2c-5269f1222c6f
{
  "id": "32478070-6fc9-4b26-8f2c-5269f1222c6f",
  "status": 200,
  "scopes": ["nt:phone", "nt:legal_name"],
  "label": "Ref Customer #41471",
  "link": "https://nametag.co/i/utl2ffahuw7lqf"
  "subject": "ewyzkwmoor5xg5ead2zjswudjq@5lsqfg1luqzb9s.nametag.co"
}

Update a request

Update the label on a request; no other fields of the request can be updated and previous labels are overwritten and not retained. Labels are only available with certain paid plans; contact sales@nametag.co for more information.

Method: PATCH

URL: https://nametag.co/api/requests/REQUEST-ID

Authentication: API key

Request: A JSON object with the following fields:

Field Type Meaning
label string (optional) A label for the request; maximum 64 characters; only available with certain plans

Response: A JSON object with the following fields:

Field Type Meaning
id string A unique identifier for this request
status number The status code for the request. Always 100 (request pending) when the request is initially created.
scopes list of string An array of the scopes that were requested.
link string An authorization link. Passing this link to the user will prompt them to complete the request.
label string The label for the request; only available with certain plans

Example:

$ curl -u :$APIKEY \
  -X PATCH \
  https://nametag.co/api/requests \
  -d '{
    "label": "updated label text"
}'
{
  "id": "32478070-6fc9-4b26-8f2c-5269f1222c6f",
  "status": 100,
  "scopes": ["nt:phone", "nt:legal_name"],
  "link": "https://nametag.co/i/utl2ffahuw7lqf",
  "label": "updated label text"
}

Cancel a request

Abort a request, invalidating the link for this request that was returned or sent via SMS when it was created. If the user has opened the request on their mobile device, it will close with a message that the request was canceled. A request is valid for 168 hours (7 days) from its creation unless it is canceled.

Method: DELETE

URL: https://nametag.co/api/requests/REQUEST-ID

Authentication: API key

Example:

When the request is complete:

$ curl -u :$APIKEY \
  -X DELETE \
  https://nametag.co/api/requests/32478070-6fc9-4b26-8f2c-5269f1222c6f

Response:

On success the response will be the HTTP code 204 (No content) with an empty body.

Get request details

Fetch the details of a request, including the scopes and scan information associated with it.

Method: GET

URL: https://nametag.co/api/requests/REQUEST-ID/detail or https://nametag.co/api/requests/REQUEST-TICKET-ID/detail

Authentication: API key

Response: A JSON object with the following fields:

Field Type Meaning
id string A unique identifier for this request
ticket string The ticket ID for this request
request_label string The label for the request; only available with certain plans
status number The status code for the request. See the below table for possible values.
properties list of JSON objects with fields scope and value The properties that were shared with you.
selfie RequestDetailsSelfie The selfie scan information.
document RequestDetailsDocument The document scan information.
device RequestDetailsDevice Details on the end-user’s mobile device
privacy RequestDetailsPrivacy Details on end-user consent and data storage locations
created_at RFC 3339 full-date Timestamp of when this request was created
updated_at RFC 3339 full-date Timestamp of the last time this request was updated
completed_at RFC 3339 full-date Timestamp of the time at which this request was completed
request_expires_at RFC 3339 full-date Timestamp of when this request expires
scopes_expire_at RFC 3339 full-date Timestamp of when the shard data elements are no longer available
revoked_at RFC 3339 full-date Timestamp of when the request was revoked by the end-user
reject_reason number The reason a request did not pass validation. See the table below for possible values.
manual_validation boolean Was the request reviewed and approved by a human?
manual_validation_completed_at RFC 3339 full-date Timestamp of when the manual validation was completed
integrity_ok boolean Is the integrity of the device and app valid?
account_info RequestDetailsAccountInfo Details about the account that was managed via Autopilot
is_self_service boolean Was this a self-service request? (aka, Autopilot versus Copilot)
Status Meaning
100 The request is pending.
101 The user has opened the request.
200 The request has been accepted.
403 The user has revoked their shared data.
404 The request has been canceled.
410 The request has expired.
411 The shared scopes have expired.
550 The user’s ID scan has been rejected and is pending appeal.
551 The user’s ID scan has been rejected.
552 The user’s ID scan has been rejected and flagged as a fraud attempt.
Reject Reason Meaning
1 The device is invalid
2 The document is invalid
3 The selfie is invalid

RequestDetailsSelfie

The type RequestDetailsSelfie has the following fields:

Field Type Meaning
taken_at RFC 3339 full-date Timestamp at which the selfie was taken
annotated_image URL A URL to the annotated image of the selfie, redacted to remove any sensitive information.
depth_map URL A URL to the depth map of the selfie. (only present when a depth map is available)
depth_map_ok boolean Does the depth map indicate a real person?
depth_map_confidence number The confidence (between 0 and 1) that the depth map represents a real person (only present when a depth map is available).
face_match_ok boolean Does face match ID photo?
face_match_confidence number The confidence (between 0 and 1) that the selfied matches the ID photo.
selfie_chain_count number The number of selfies in the chain.
selfie_chain_ok boolean Whether the selfie chain check has passed.
selfie_chain_confidence number The confidence (between 0 and 1) that the selfie chain is valid.
app_attestation_ok boolean Whether the app attestation check has passed.
app_attestation_confirmed_at RFC 3339 full-date Timestamp of when app attestation was checked

RequestDetailsDocument

The type RequestDetailsDocument has the following fields:

Field Type Meaning
scanned_at RFC 3339 full-date Timestamp at which the document was scanned.
annotated_image URL A URL to the annotated image of the selfie, redacted to remove any sensitive information.
structure_ok boolean Whether the document structure is correct.
structure_confidence number The confidence (between 0 and 1) that the document structure is correct.
cardcheck_ok boolean Whether a real document was scanned
cardcheck_confidence number The confidence (between 0 and 1) that a real document was scanned
app_attestation_ok boolean Whether the app attestation check has passed.
app_attestation_confirmed_at RFC 3339 full-date Timestamp of when app attestation was checked
address_location RequestDetailsLocation Details about the address location from the scanned identity document, if available

RequestDetailsLocation

The type RequestDetailsLocation has the following fields:

Field Type Meaning
latitude number Degress latitude
longitude number Degrees longitude
city string Name of the city on the ID
subdivision string Name of the state, region, or other national subdivision on the ID
country string Name of the country on the ID
residential boolean This is a residential address
business boolean This is a business address
po_box boolean This is a Post Office Box

RequestDetailsDevice

The type RequestDetailsDevice has the following fields:

Field Type Meaning
device_verified_at RFC 3339 full-date Timestamp at which the device was first verified.
device_public_key string Public keys of the end-user’s mobile device cryptographic coprocessor.
app_version string Version of the Nametag mobile app in use.
device_user_agent string User agent of the request, including information on the application and the mobile device.
device_os string Operating system and version in use on the end-user’s mobile device?
app_integrity_ok boolean Is the application a valid Nametag application?
device_integrity_ok boolean Is the device a genuine unmodified device according to the manufacturer.
device_integrity_confirmed_at RFC 3339 full-date Timestamp at which the device integrity was confirmed.
ip_location RequestDetailsLocation Details on the location of the IP address of the end-users’s mobile device, if available.

RequestDetailsPrivacy

The type RequestDetailsPrivacy has the following fields:

Field Type Meaning
biometric_consent_provided_at RFC 3339 full-date Timestamp at which the end-user consented to sharing biometric information.
data_sharing_consent_provided_at RFC 3339 full-date Timesstamp at which the end-user shared data with the requestor.
storage_region string Region code for the region in which the data is stored.
processing_region string Region code for the region in which the data was processed.

RequestDetailsAccountInfo

The type RequestDetailsAccountInfo has the following fields:

Field type Meaning
directory_kind string Type of directory; one of azure-ad, okta, duo, or onelogin
email string Email address in the directory of the person who reset their password
env_name string Name of the Nametag environment where the directory is configured
env_id string ID of the Nametag environment where the directory is configured
name string Name in the directory of the person who reset their password

Example:

$ curl -u ":$API_KEY" \
  https://nametag.co/api/requests/ca2aeb0b-8a2b-43e8-8200-c27a9053d47e/detail

Response:

{
  "id": "ca2aeb0b-8a2b-43e8-8200-c27a9053d47e",
  "ticket": "pgqvp3hfgtr8bv",
  "request_label": "",
  "status": 200,
  "properties": [
    {
      "scope": "nt:legal_name",
      "value": "Andrew Justin Caird"
    }
  ],
  "selfie": {
    "taken_at": "2024-04-07T16:43:09.854922468Z",
    "annotated_image": "https://nametagusercontent.com/profile-pictures/cfeb/d74b/cfebd74bb7751e39e453b0e3e453bfff454d81b959a4350e824c1aaaa36358aa82f510ea",
    "face_match_ok": true,
    "face_match_confidence": 0.996,
    "selfie_chain_count": 1,
    "selfie_chain_ok": true,
    "selfie_chain_confidence": 1,
    "app_attestation_ok": true,
    "app_attestation_confirmed_at": "2024-04-07T16:43:09.854922468Z"
  },
  "document": {
    "scanned_at": "2024-04-07T16:42:56.71890669Z",
    "annotated_image": "https://nametagusercontent.com/profile-pictures/313a/8829/313a882962331065489d37cbd8a869cf4687307bd69d06a2451b12ae5cccf82b4577cbf4",
    "structure_ok": true,
    "structure_confidence": 0.949,
    "cardcheck_ok": true,
    "cardcheck_confidence": 1,
    "app_attestation_ok": true,
    "app_attestation_confirmed_at": "2024-04-07T16:42:56.71890669Z",
    "address_location": {
      "latitude": 42.2698642,
      "longitude": -83.7030167,
      "city": "Ann Arbor",
      "subdivision": "MI",
      "country": "",
      "residential": true,
      "business": false,
      "po_box": false
    }
  },
  "device": {
    "device_verified_at": "2024-04-02T19:55:00.455073Z",
    "device_public_key": "08:b3:82:55:12:cc:ea:4c:52:80:93:7c:05:91:9b:76",
    "app_version": "4.0.27-28",
    "device_user_agent": "nametag.hello.dev/4.0.27-28; iOS/17.3.1; iPhone SE (2nd generation)",
    "device_os": "iOS/17.3.1; iPhone SE (2nd generation)",
    "app_integrity_ok": true,
    "device_integrity_ok": true,
    "device_integrity_confirmed_at": "2024-04-07T16:38:13Z"
  },
  "privacy": {
    "biometric_consent_provided_at": "2024-04-07T16:25:57.48328Z",
    "data_sharing_consent_provided_at": "2024-04-07T18:43:21.519896Z",
    "storage_region": "us",
    "processing_region": "us"
  },
  "created_at": "2024-04-07T16:21:55.832224Z",
  "updated_at": "2024-04-07T16:43:20.972052Z",
  "completed_at": "2024-04-07T18:43:21.519896Z",
  "request_expires_at": "2024-04-14T16:21:55.80625Z",
  "scopes_expire_at": "2024-04-10T18:43:21.519896Z",
  "integrity_ok": true,
  "account_info": null,
  "is_self_service": true
}

People API

The People API allows you to fetch and manage the data that people have shared with you.

Get properties

Method: GET

URL: https://nametag.co/people/SUBJECT/properties/SCOPES

Authentication: API key for any subject, or an ID token is if SUBJECT is special value me.

Parameters:

  • SUBJECT - The subject you got back from the token endpoint which uniquely identifies the person. You can use the special value me with ID token authentication to fetch information about the person for whom the ID token was issued.

  • SCOPES - A comma-separated list of the scopes you want to fetch.

Response:

{
  "env_id": "ENV",
  "subject": "SUBJECT",
  "properties": [ PROPERTY, ... ]
  "requests": [ REQUEST, ... ]
}

The response contains a list of properties that you requested. Each PROPERTY has the following fields:

Field Type Description
scope string The scope you requested.
value varies with scope The value of the property. The type of this field varies depending on the scope. See this table.
expires RFC 3339 date-time When your access to this data expires
status int A value that tells you the disposition of the property. The value 200 means the data was shared. The value 403 means the data has not been shared, the person has revoked your access, or 410 meaning the request has expired.

Each request describes a single request for information. The REQUEST has the following fields:

Field Type Description
created_at RFC 3339 date-time The time that the request was initiated
id string The ID of the request (use with the requests API
scopes list of string The scopes requested
status int The status of the request, 200 means accepted, 403 means rejected or canceled.

Errors:

  • 400 Bad Request - The one or more of the scopes provided are invalid or not registered.

Example:

$ SUBJECT=vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co
$ curl -u ":$API_KEY" \
  "https://nametag.co/people/$SUBJECT/properties/nt:email,nt:legal_name"

Response:

{
  "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
  "properties": [
    {
      "expires": 1637321520,
      "scope": "nt:email",
      "value": "ross@nametag.co",
      "status": 200
    },
    {
      "expires": 1637321520,
      "scope": "nt:legal_name",
      "value": "Ross Kinder",
      "status": 200
    }
  ],
  "requests": [
    {
      "created_at": "2022-12-18T19:15:42.315853Z",
      "id": "f5cb153e-b96a-42c6-a1c0-f5a27d065fea",
      "scopes": [
        "nt:email",
        "nt:legal_name"
      ],
      "status": 200
    }
  ]
}

Example using ID token:

$ ID_TOKEN=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvaXQiLCJleHAiOjIxNDc0ODM2NDcsImlhdCI6MTYzNzIzNTEyNSwiaXNzIjoibmFtZXRhZy5jbyIsIm5iZiI6MTYzNzIzNTEyNSwic3ViIjoidmtsamlwa2FpbzJhcDY2M2RvNTRyNWZwMmFANWxzcWZnMWx1cXpiOXMubmFtZXRhZy5jbyJ9.P-elo7PUVC9dIBSV_UgoFbaHc2yATNOj8jumVTF_3izs9QqZ4lslvUsfCnogc1l7oEpowCR9d2j42J6J-5LWjw
$ curl -u ":$ID_TOKEN" \
  "https://nametag.co/people/$SUBJECT/properties/nt:email,nt:legal_name"

Response:

{
  "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
  "properties": [
    {
      "expires": 1637321520,
      "scope": "nt:email",
      "value": "ross@nametag.co",
      "status": 200
    },
    {
      "expires": 1637321520,
      "scope": "nt:legal_name",
      "value": "Ross Kinder",
      "status": 200
    }
  ]
}

Delete properties

A person may revoke your access to a scope at any time. Less commonly, you can also remove a user’s access, for example if a user deletes their account or requests that their data be unshared via your app.

Method: DELETE

URL: https://nametag.co/people/SUBJECT/properties/SCOPES

Authentication: API key for any subject. ID token is if the subject is special value me.

Parameters:

  • SUBJECT - The subject you got back from the /token endpoint which uniquely identifies the person. You can use the special value me with ID token authentication to revoke a scope on behalf of a person to whom the ID token was issued.
  • SCOPES - A comma-separated list of the scopes you want to revoke.

Request: none

Response: none

Example:

CLIENT_ID=obo0jukwhhlbo8
CLIENT_SECRET=ed1227ffbd35ff2b83bc8bd2c6af6473e596be875f094ef08da6a3c041d584f0
SUBJECT=vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co
curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -X DELETE \
  "https://nametag.co/people/$SUBJECT/properties/nt:email,nt:legal_name"

Get properties in bulk

This endpoint returns properties for multiple people at a time. For each person, specify the subject and the scopes you are requesting. The response will contain an object for each of the subjects you provided.

Note: We recommend a batch size of around 512 people per request. The Nametag API does not strictly limit the number of items that you request, but the requests that are too large may fail due to timeouts or size restrictions on the response.

Method: POST

URL: https://nametag.co/people/bulk

Authentication: API key

Request body:

{
  "requests": [ BULK-REQUEST, ... ]
}

Each BULK-REQUEST is an object consisting of the following fields:

Field Type Description
subject string The SUBJECT returned from the token endpoint
scopes list of string The scopes requested

Response:

The response will contain one entry corresponding to item in the requests list.

{
  "data": [
    {
      "subject": "SUBJECT",
      "properties": [ PROPERTY, ... ],
    },
    ...
  ]
}

Example:

curl -u ":$API_KEY" https://nametag.co/people/bulk \
  -d '{
  "requests": [
    {
      "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
      "scopes": [
        "nt:email",
        "nt:legal_name"
      ]
    }
  ]
}'

Response:

{
  "data": [
    {
      "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
      "properties": [
        {
          "expires": 1637321520,
          "scope": "nt:email",
          "value": "ross@nametag.co",
          "status": 200
        },
        {
          "expires": 1637321520,
          "scope": "nt:legal_name",
          "value": "Ross Kinder",
          "status": 200
        }
      ]
    }
  ]
}

Compare values

This endpoint compares a set of expected values of a scope for a subject and returns a confidence score that tells you if the subject matches what you expect.

This is useful if your user already has an account with your service and you need to connect them to a Nametag subject.

Note: For now, the only supported scope is nt:legal_name.

Method: POST

URL: https://nametag.co/people/:subject/compare

Authentication: API key

Request body:

{
  "expectations": [
    {
      "scope": "nt:legal_name",
      "value": "Alice Smith",
    },
  ]
}

Response:

The response will contain one entry corresponding to each item in the expectations array. The scope and value from the request will be echoed back as scope and expected, respectively. The value is the actual value of the scope (as would be returned from the get properties endpoint. The confidence that the expected data matches the actual value of the scope is returned as a float in the range 0.0-1.0 as match_confidence.

{
  "confidence": 0.9,
  "comparisons": [
    {
      "scope": "nt:legal_name",
      "expected": "First Last",
      "value": "First Middle Last",
      "match_confidence": 0.9
    }
  ]
}

Compare selfie

This endpoint compares a photo you upload to the subject’s validated selfie photo provided as part of scanning their government ID. The user must have successfully validated at least one selfie photo against their government ID for this endpoint to return a result. The user must have authorized the nt:profile_picture scope.

This is useful if your want to tell if a photo of a user matches the photo on their government ID.

Note: Although the nt:profile_picture scope is required, this endpoint does not compare the uploaded photo against the profile picture. Instead, it compares the actual selfie(s) provided by the subject.

Method: POST

URL: https://nametag.co/people/:subject/compare/selfie

Authentication: API key

Request body: JPEG image data (Content-Type: image/jpeg)

Response:

{
  "confidence": 0.9,
}

Webhooks

Webhooks allow you to handle events initiated by Nametag. When events of interest occur, our service will make an HTTPS request to your service. Webhooks are configured on a per-environment basis in the developer console.

Authentication: Your service should verify that the requests to your webhook endpoint actually originate from Nametag. Each request to your service includes a header X-Nametag-Signature whose value is the hex-encoded HMAC-SHA256 of the body of the request using the webhook’s SHARED-SECRET as the key. The shared secret can be found in the developer console.

Retries: If your service returns an error status code (>= 400), or if we cannot connect due to a network or certificate error, then Nametag will retry the request up to five times at 30 second intervals. You can see a history of our attempts to deliver webhooks in the developer console.

Note: Your service must present a valid, publicly trusted SSL/TLS certificate. For development, we recommend ngrok. For production use we recommend Let’s Encrypt

Share event

This event is emitted whenever a person shares information with you, or when they update information they have previously shared.

Event type: share

Request body:

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

Example: (whitespace has been added to the response for clarity)

POST https://example.com/webhook HTTP/1.1
Date: Thu, 18 Nov 2021 11:55:09 GMT
Content-type: application/json
User-agent: Nametag-Webhooks/20211116T214921.7e635fd.ci
X-Nametag-ID: 925dfd28-5213-42d9-9320-f1f6d0c8de09
X-Nametag-Signature: c47c087cef9d7816fd625a4383c73ee67de833cbf4376f45aa8a9ef1277c7c81

{
  "event_type": "share",
  "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
  "request": "f9cbc40a-5da2-4f1c-84a6-f8e097fca03c",
  "env_name": "Live",
  "org_name": "My Company",
  "scopes": [
    "nt:email",
    "nt:legal_name",
    "nt:name"
  ]
}

Example: Verifying the signature

$ WEBHOOK_SHARED_SECRET=webhook-683fb6598c7faa4f05e4e693d3686f5faa6b9cd7bb646c5254edd3cb880f4225
$ echo -n '{"event_type":"share",'\
    '"subject":"vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",'\
	'"request":"f9cbc40a-5da2-4f1c-84a6-f8e097fca03c",'\
    '"scopes":["nt:email","nt:name","nt:legal_name"]}' |\
  openssl dgst -sha256 -hmac "$WEBHOOK_SHARED_SECRET"
c47c087cef9d7816fd625a4383c73ee67de833cbf4376f45aa8a9ef1277c7c81

The event request body contains the following fields:

Field Type Description
event_type string Always "share" for this event type
subject string The subject that shared the data
request_id string The ID of the most recent request which was returned by the create a request API, if used. This field may be omitted when the user changes shared data outside the context of a pending request, such as by using the “Vault” tab in the Nametag app.
env_name string The currently configured name of the environment that generated the webhook
org_name string The currently configured name of the organization in which the environment is configured
scopes list of string The list of currently shared scopes

Revoke event

This event is emitted when a person revokes access to information they’ve previously shared with you.

Event type: revoke

Request body:

{
  "event_type": "revoke",
  "subject": "SUBJECT",
  "request": "REQUEST_ID",
  "env_name": "ENVIRONMENT_NAME",
  "org_name": "ORGANIZATION_NAME",
  "scopes": ["SCOPE", ...]
}

Example:

POST https://trynametag.com/webhook HTTP/1.1
Date: Thu, 18 Nov 2021 11:55:23 GMT
Content-type: application/json
User-agent: Nametag-Webhooks/20211116T214921.7e635fd.ci
X-Nametag-ID: 4f94f7a0-5bdf-409b-ae84-2aff8c95eab0
X-Nametag-Signature: b7aad74f36f50e7b15112bea178b25001c45726715cf19a4328e5b22f89a9b7f

{
  "event_type": "reject",
  "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
  "env_name": "Live",
  "org_name": "My Company",
  "scopes": [
    "nt:email",
    "nt:legal_name",
    "nt:name"
  ]
}

The event request body contains the following fields:

Field Type Description
event_type string Always "revoke" for this event type
subject string The Subject that initially shared the data
env_name string The currently configured name of the environment that generated the webhook
org_name string The currently configured name of the organization in which the environment is configured
scopes list of string The list of revoked scopes

Recover event

This event is emitted whenever a person recovers an account using a connected directory service such as Azure AD or Okta.

Event type: recover

Request body:

{
  "event_type": "recover",
  "subject": "SUBJECT",
  "directory": "DIRECTORY-ID",
  "external_id": "EXTERNAL-ID",
  "action": "ACTION",
  "date": "DATE"
  "env_name": "ENVIRONMENT_NAME",
  "org_name": "ORGANIZATION_NAME",
}

The event request body contains the following fields:

Field Type Description
event_type string Always "recover" for this event type
subject string The Nametag identifier of the person who recovered an account
directory string The ID of the directory service that was used to recover the account
external_id string The ID of the user in the directory service
action string The type of recovery that occurred, either reset-password, or reset-mfa
date RFC 3339 full-date The time when the recovery completed.
env_name string The currently configured name of the environment that generated the webhook
org_name string The currently configured name of the organization in which the environment is configured

Example: (whitespace has been added to the response for clarity)

POST https://example.com/webhook HTTP/1.1
Date: Thu, 18 Nov 2021 11:55:09 GMT
Content-type: application/json
User-agent: Nametag-Webhooks/20211116T214921.7e635fd.ci
X-Nametag-ID: 2744d75e-0eb9-448d-8b70-cd59ee5a8471
X-Nametag-Signature: a83e8857e70bcbd923d7180582b5877123e732d25fefc4af170f83a94c250c09

{
  "event_type": "recover",
  "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
  "directory": "132bf0fb-55dd-4b19-ad54-e43a85c8bd50",
  "external_id": "alice@example.com",
  "action": "reset-password",
  "env_name": "My Environment",
  "org_name": "My Company"
}

Data types

Government ID Details

When fetching a property with the scope nt:govtid_details, the data returned is a JSON object with the following structure:

Field Type Description
type string The type of document. driver_license or passport.
issuer string The authority that issued the document. For passports, this is the ISO 3166-1 Alpha-3 country code (e.g. USA). For driver licenses, this is the country code followed by a country-specific identifier for the state or province (e.g. USA.CA)
number string The identifying number of the driver license or passport.
expiration RFC 3339 full-date The date after which the document is no longer valid

Configuration API

Use the configuration API to manage the configuration of your organizations and environments. All requests to the configuration API are authenticated with API keys.

Environment

An environment is the unit of privacy isolation in Nametag. The Environment object contains the following fields:

Field Type Description
id string The identifier for this environment
name string The internal name for this environment, e.g. “Live”
public_name string The name of the environment that is shared with people, e.g. “Acme Corporation”
description string A description of what your company or app does. Displayed to people in the Nametag mobile app.
logo_url string A URL to your logo, which is displayed in the Nametag mobile app.
terms_of_service_url string A URL that points to your terms of service or privacy policy, e.g. https://example.com/privacy. This is linked in the Nametag mobile app.
callback_urls list of string A list of URLs that are acceptable as a redirect_uri parameter to /authorize.
webhook_shared_secret string The shared secret to be used for authenticating webhooks.
webhooks list of WebhookDefinition A list of webhooks.
templates list of Template A list of request templates.

WebhookDefinition

The type WebhookDefinition defines a webhook. It contains the following fields:

Field Type Description
url string The URL in your service that should be called, e.g. https://example.com/__callback
enabled boolean If true, then calls to this webhook should be made.
events list of string The names of the events that should be sent.

Template

The type Template defines a request template. A request template provides greater control over your request than is possible with the create a request endpoint.

It contains the following fields:

Field Type Description
id string A unique identifier for the template
created_at RFC 3339 full-date When the template was created
name string A descriptive name of the template
is_default bool If true then this is the default template used when a template is not explicitly specified. There must be exactly one default template.
scope_definitions list of TemplateScopeDefinition A list of scopes that are requested when requests are created with this template.
scopes_expire_in int How long the data sharing authorization should last, in seconds.
enabled bool If true, then this template is enabled for requests. The default template must be enabled.
headline string The text that appears at the top of the mobile app when showing the request
qr_headline string The text that appears above the QR code when directing the user from desktop to mobile.
expiration_text string The text that describes when the request expires. This should include {{.TTL}} which is a placeholder for the expiration of the data sharing authorization in human readable form, e.g. “3 hours”
accept_text string The text on the accept button in the mobile app.
accepted_text string The text that appears on the confirmation view after a request has been accepted.
install_message_sms string The contents of the SMS message sent to users to direct them to the mobile app. This must contain the {{.Link}} which is a placeholder for the actual link.
require_selfie_reverification bool If true, existing users must provide a new selfie to validate their identity.

TemplateScopeDefinition

The type TemplateScopeDefinition defines a scope that is requested when a request is created with a template. It contains the following fields:

Field Type Description
scope string The name of the scope that is requested
restrict_email_domains list of string If the scope is nt:email, accept only emails from one of the specified domains. Optional

List environments

Returns a list of all environments that you have access to.

Method: GET

URL: https://nametag.co/api/envs

Authentication: API key

Response:

{
  "envs": [ ENV, ... ]
}

Example:

$ export APIKEY="..."
$ curl -u :$APIKEY https://nametag.co/api/envs

Response:

{
  "envs": [
    {
      "id": "5lsqfg1luqzb9s",
      "name": "Sidecar Production",
      "public_name": "Sidecar",
      "description": "Like Uber, but for rides in motorcycle sidecars.",
      "logo_url": "https://nametagusercontent.com/app-icons/fa21/f7d7/fa21f7d7e4d2eacec7331de48df71e29cfe5fca2d8c629634e9e69a2042c26b9",
      "terms_of_service_url": "https://example.nametag.co/terms",
      "callback_urls": [
        "https://trynametag.com/callback"
      ],
      "webhook_shared_secret": "webhook-683fb6598c7faa4f05e4e693d3686f5faa6b9cd7bb646c5254edd3cb880f4225",
      "webhooks": [
        {
          "url": "https://trynametag.com/webhook",
          "enabled": true,
          "events": [
            "share",
            "reject"
          ]
        }
      ]
    }
  ]
}

Create

Creates a new environment

Method: POST

URL: https://nametag.co/api/envs

Authentication: API key

Request: empty

Response:

{
  "id": "ENV-ID"
}

Example:

$ curl -u :$APIKEY \
    -X POST \
    https://nametag.co/api/envs

Response:

{
  "id": "x0n8vfkfcmh3ks"
}

Get

Fetch the settings for an environment.

Method: GET

URL: https://nametag.co/api/envs/ENV-ID

Authentication: API key

Response: an Environment object

Example:

curl -u :$APIKEY https://nametag.co/api/envs/x0n8vfkfcmh3ks

Response:

{
  "id": "5lsqfg1luqzb9s",
  "name": "Sidecar Production",
  "public_name": "Sidecar",
  "description": "Like Uber, but for rides in motorcycle sidecars.",
  "logo_url": "https://nametagusercontent.com/app-icons/fa21/f7d7/fa21f7d7e4d2eacec7331de48df71e29cfe5fca2d8c629634e9e69a2042c26b9",
  "terms_of_service_url": "https://example.nametag.co/terms",
  "callback_urls": [
    "https://trynametag.com/callback"
  ],
  "webhook_shared_secret": "webhook-683fb6598c7faa4f05e4e693d3686f5faa6b9cd7bb646c5254edd3cb880f4225",
  "webhooks": [
    {
      "url": "https://example.com/webhook",
      "enabled": true,
      "events": [
        "share",
        "reject"
      ]
    }
  ]
}

Update

Change settings for an environment. All the request fields are optional, and only fields that are provided will be changed.

Method: PATCH

URL: https://nametag.co/api/envs/ENV-ID

Authentication: API key

Request:

Each field of the request is optional. Refer to the Environment object for descriptions of each field.

Field Type Description
name string Update the name of the environment
public_name string Update the public name of the environment
description string Update the description
logo_url string Update the logo URL
terms_of_service_url string Update the terms of service URL.
callback_urls list of string Set the list of allowed OAuth 2.0 callback URLs
remove_webhooks list of string Remove webhooks from the environment (URLs of the webhooks to remove)
add_webhooks list of WebhookDefinition Add webhooks to the environment

To modify a webhook, include both the remove_* and add_* in the same request. For example, to replace an webhook, include both remove_webhooks and add_webhooks in your request.

Example:

$ curl -u :$APIKEY https://nametag.co/api/envs/x0n8vfkfcmh3ks -X PATCH -d '{
  "name": "Example app",
  "remove_webhook": ["https://example.com/webhook"],
  "add_webhook": [
    {
      "url": "https://example.com/webhook2",
      "enabled": true,
      "events": ["share", "reject"]
    }
  ]
}'

Method: POST

URL: https://nametag.co/api/envs/ENV-ID/logo

Authentication: API key

Request: A PNG, SVG, or JPEG of your service’s logo. Set the Content-type request header to one of image/png, or image/svg+xml, or image/jpeg.

Response: none

Example:

$ curl -u :$APIKEY \
    -X POST \
    -H "Content-type: image/png" \
    -T "logo512.png" \
    https://nametag.co/api/envs/x0n8vfkfcmh3ks/logo

# check the environment
$ curl -u :$APIKEY https://nametag.co/api/envs/x0n8vfkfcmh3ks | jq -r .logo_url
https://nametagusercontent.com/app-icons/fa21/f7d7/fa21f7d7e4d2eacec7331de48df71e29cfe5fca2d8c629634e9e69a2042c26b9

Remove

Remove an environment.

Method: DELETE

URL: https://nametag.co/api/envs/ENV-ID

Request: none

Response: none

$ curl -u :$APIKEY \
    -X DELETE \
    https://nametag.co/api/envs/x0n8vfkfcmh3ks

Directories

A directory represents a connection to an external directory, which enables self-service account recovery and/or validating the identity of users in the directory.

Create

Create a directory.

Method: POST

URL: https://nametag.co/api/envs/ENV-ID/directories

Request:

{
  "kind": "DIRECTORY-KIND"
}

Where kind is one of azure-ad, ad or okta.

Response:

{
  "id": "DIRECTORY-ID"
}

List

Fetches information about each directory

Method: GET

URL: https://nametag.co/api/envs/ENV-ID/directories

Response:

{
  "directories": [
    {
      "id": "DIRECTORY-ID",
      "name": "example.com",
      "kind": "azure-ad",
      "count": 1433,
      "last_sync": "2023-07-10T14:03:13Z",
      "last_sync_error": ""
    }
  ]
}
  • The name field of each directory is derived from inspecting the directory itself, for example for kind azure-ad, name is the primary domain name configured in Azure AD.
  • The count field is the number of entries in the directory, as of the most recent synchronization.

Delete

Deletes a directory

Method: DELETE

URL: https://nametag.co/api/envs/ENV-ID/directories/DIRECTORY-ID

Request: none

Response: none

Synchronize

Trigger synchronization of the directory.

Note: Synchronoization happens automatically once per hour.

Method: POST

URL: https://nametag.co/api/envs/ENV-ID/directories/DIRECTORY-ID/sync

Request: none

Response: none

Authorize

Return a URL, which when visited in a browser, will initiate a connection between Nametag and the directory. Completing this flow will replace any existing authorization, if present.

Method: POST

URL: https://nametag.co/api/envs/ENV-ID/directories/DIRECTORY-ID/authorize

Request: none

Response:

{
  "redirect_url": "https://directory-provider/authorize?..."
}

Templates

A template defines certain parameters for a request. A request can be created with the template query parameter to /authorize to pre-fill the request with the parameters defined in the template.

Note: there are no APIs for listing or fetching templates. Instead, they are returned as part of the GET /env/:env API.

You must always have exactly one template that is the default. The default template is used when a request is created without specifying a template.

Create a template

Creates a new template.

All fields in the request body are optional, if not provided they will have their default values.

Method: POST

URL: https://nametag.co/api/envs/ENV-ID/templates

Request:

{
  "name": "Transaction Authorization",
  "headline": "ACME needs to your identity for this transaction",
  "qr_headline": "ACME must verify your identity to continue.",
  "expiration_text":  "Expires in {{.TTL}}",
  "accept_text": "Approve transaction",
  "accepted_text":  "You've approved your transaction",
  "install_message_sms": "ACME needs to check your ID to continue. Click this link to continue: {{.Link}}",
  "is_default":  false,
  "scope_definitions": [
    {
      "scope": "nt:legal_name"
    },
    {
      "scope": "nt:email",
      "restrict_email_domains": ["example.com"]
    }
  ],
  "scopes_expire_in":  86400,
  "enabled": true,
  "require_selfie_reverification":  false
}

Response:

{
  "id": "a7da6fc2-ba44-44df-a863-3ac9f58b5ba6"
}

Example:

$ curl -u :$APIKEY \
  -X POST \
  https://nametag.co/api/envs/x0n8vfkfcmh3ks/templates \
  -d '{"name": "Transaction Authorization"}'

Modify a template

Updates a template. The request body may contain any of the fields from the Template object. Fields that are omitted remain unchanged.

Method: PATCH

URL: https://nametag.co/api/envs/ENV-ID/templates/TEMPLATE-ID

Request:

{
  "name": "Transaction Authorization",
  "headline": "ACME needs to your identity for this transaction",
  "qr_headline": "ACME must verify your identity to continue.",
  "expiration_text":  "Expires {{.TTL}}",
  "accept_text": "Approve transaction",
  "accepted_text":  "You've approved your transaction",
  "install_message_sms": "ACME needs to check your ID to continue. Click this link to continue: {{.Link}}",
  "is_default":  false,
  "scope_definitions": [
    {
      "scope": "nt:legal_name"
    },
    {
      "scope": "nt:email",
      "restrict_email_domains": ["example.com"]
    }
  ],
  "scopes_expire_in":  86400,
  "enabled": true,
  "require_selfie_reverification":  false
}

Response: none

Example:

Update the headline for a template:

$ curl -u :$APIKEY \
  -X PATCH \
  https://nametag.co/api/envs/x0n8vfkfcmh3ks/templates/a7da6fc2-ba44-44df-a863-3ac9f58b5ba6
{
  "headline": "ACME needs to know who you are"
}

Delete a template

Removes a template.

Method: DELETE

URL: https://nametag.co/api/envs/ENV-ID/templates/TEMPLATE-ID

Request: none

Response: none

Example:

Update the headline for a template:

$ curl -u :$APIKEY \
  -X DELETE \
  https://nametag.co/api/envs/x0n8vfkfcmh3ks/templates/a7da6fc2-ba44-44df-a863-3ac9f58b5ba6

Organizations

An organization is a singleton that represents global state about your relationship to Nametag.

Get

Get the organization.

Method: GET

URL: https://nametag.co/api/org

Authentication: API key

Response:

{
  "name": "Acme Corp",
  "role": "owner",
  "envs": ["cfln7ldhawwlen", "nwixcd2qkbth7h"]
}

The response is an object that contains the following fields:

Field Type Description
name string The name of the organization
role string Your role on the organization, which is either owner, admin, user or limited.
envs list of string A list of the environment IDs that you have access to.

Example:

curl -u :$APIKEY https://nametag.co/api/org

Response:

{
  "name": "Acme Corp",
  "role": "admin",
  "envs": [
    "cfln7ldhawwlen",
    "nwixcd2qkbth7h"
  ]
}

List members

Returns a list of the members of your organization

Method: GET

URL: https://nametag.co/api/org/members

Authentication: API key

Request: none

Response:

{
  "members": [ ORG-MEMBER, ... ]
}

Each ORG-MEMBER is an object consisting of:

Field Type Description
member_id string An identifier for the fact of this person being a member of the specified organization.
role string The person’s role on the organization. One of reader, admin, or owner
name string The person’s name
email string The person’s email address
invited_email string The email address that was invited to the organization (which could differ from the email address they entered into their Nametag app)
profile_picture URL A URL to the person’s preferred profile picture. Nametag checks that the image provided is the same person as pictured on their identity document.
is_self boolean true if this person is you

Invite a person to your organization

Invites a new person to join your organization. This API sends an email to the address specified. When the person accepts the invitation, they will have joined the organization. The person must use the Nametag app to authenticate prior to joining the organization.

Method: POST

URL: https://nametag.co/api/org/members

Authentication: API key

Request:

{
  "email": "alice@example.com"
}

Response: none

Remove an organization member

Removes a person from an organization.

Method: DELETE

URL: https://nametag.co/api/org/members/MEMBER-ID

Authentication: API key

Request: none

Response: none

Set a member’s role

Assign a role to a member

Method: PATCH

URL: https://nametag.co/api/org/members/MEMBER-ID

Request:

{
  "role": "admin"
}

The role must be one of reader, or admin. You must have at least one active member marked as admin.

Response: none

API Keys

As mentioned in Authentication above, API keys are used to authenticate request to the Nametag API. An API key may be global (meaning it applies to all Environments), or it may be local (it applies only to one environment).

List

List the API Keys that you have access to.

Method: GET

URL: https://nametag.co/api/apikeys

Authentication: API key

Response:

{
  "apikeys": [
    {
      "id": "06c6a11a-c78e-488f-9b58-f73362309ea0",
      "name": "Staging API Key",
      "created_at": "2022-03-15T22:39:59Z",
      "role": "admin",
      "enabled": true
    }
  ]
}

Each item of apikeys is an object that contains the following fields:

Field Type Description
id string The unique identifier for the API key
name string The name of the API key
envs list of string The unique identifier for the environments this API key belongs to, or ["*"] if the key applies to all environments in the organization.
role string The role associated with this key, either reader or admin.
enabled boolean Flag indicating if this API key is enabled.
created_at RFC 3339 full-date The datetime the API Key was created at

Example:

curl -u :$APIKEY https://nametag.co/api/apikeys

Response:

{
  "apikeys": [
    {
      "id": "06c6a11a-c78e-488f-9b58-f73362309ea0",
      "envs": ["*"],
      "name": "Staging API Key",
      "created_at": "2022-03-15T22:39:59Z",
      "role": "admin",
      "enabled": true
    }
  ]
}

Create

Create a new API key. This request takes an optional name for the API key to create and returns the newly created API key secret string that must be stored for future usage.

Note:

The full API key secret is not stored by Nametag, so be sure to copy the response somewhere safe for future usage.

Method: POST

URL: https://nametag.co/api/apikeys

Authentication: API key

Request:

Create a global API key:

{
  "name": "Staging API Key",
  "role": "admin",
  "enabled": true
}

Create an environment-scoped API key

{
  "name": "Staging API Key",
  "envs": ["obo0jukwhhlbo8"],
  "role": "user",
  "enabled": true
}

Response:

{
  "id": "3p0wjj3b7vyia5",
  "key": "3p0wjj3b7vyia5V2JCNoO3TqHpjT"
}

Example:

$ curl -u :$APIKEY \
  https://nametag.co/api/apikeys \
  -d '{"name": "Staging API Key"}, "envs": ["obo0jukwhhlbo8"]}'

Response:

{"key":"3p0wjj3b7vyia5V2JCNoO3TqHpjT"}

Get

Fetch information about an API key

Method: GET

URL: https://nametag.co/api/apikeys/API-KEY-ID

Authentication: API key

Request: none

Response:

{
  "id": "06c6a11a-c78e-488f-9b58-f73362309ea0",
  "envs": ["obo0jukwhhlbo8"],
  "name": "Staging API Key",
  "created_at": "2022-03-15T22:39:59Z",
  "role": "admin",
  "enabled": true
}

  1. When addressing a user, you should a person’s preferred name over their legal name, unless it is strictly necessary for your use case. This is because many people’s names on their identity documents do not match the name they would prefer you use. ↩︎

  2. For correctness and inclusivity, you should prefer a person’s full name over using the first and last names. See Falsehoods Programmers Believe About Names for details. ↩︎ ↩︎ ↩︎ ↩︎