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:

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 provide set the Authorization header:

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

You can also use HTTP basic authentication with an empty username and the API_KEY as the password:

$ curl -u ":API_KEY" https://nametag.co/api/envs

In come circumstances, you may need to use the token query parameter in lieu of the Authorization header or basic authentication:

$ curl https://nametag.co/api/envs?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:

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:

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

Response: A JSON object with the following fields:

Example:

$ 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"
{
  "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:

Response: A JSON object with the following fields:

Example:

$ curl -u :$APIKEY \
  -X POST \
  https://nametag.co/api/requests \
  -d '{
    "env": "tp7975e07n8sjl",
    "scopes": ["nt:phone", "nt:legal_name"],
    "expires_at": "2024-04-14T06:34:00-07:00"
    "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:

RequestStatus

The enumeration RequestStatus can have the following values:

RequestProgress

The enumeration RequestProgress can have the following values:

RequestProperties

The type RequestProperties has the following fields:

GovtidDetailsValue

The type GovtidDetailsValue has the following fields:

GovtidType

The enumeration GovtidType can have the following values:

RequestMobileDevice

The type RequestMobileDevice has the following fields:

Location

The type Location has the following fields:

RequestBrowser

The type RequestBrowser has the following fields:

RequestDetails

The documentation for this type is available to customers with an NDA in place. Please contact help@nametag.co for more information.

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": "shared",
  "scopes": ["nt:phone", "nt:legal_name"],
  "label": "Ref Customer #41471",
  "link": "https://nametag.co/i/utl2ffahuw7lqf"
  "subject": "ewyzkwmoor5xg5ead2zjswudjq@5lsqfg1luqzb9s.nametag.co"
}

Update a request

Method: PATCH

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

Authentication: API key

Request: A JSON object with the following fields:

Response: none

Example:

$ curl -u :$APIKEY \
  -X PATCH \
  https://nametag.co/api/requests \
  -d '{
    "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.

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:

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

The response contains the following fields:

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

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

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"
{
  "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 the 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"
{
  "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:

Each item in requests is an object consisting of the following fields:

Response:

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

Example:

$ curl -u ":$API_KEY" https://nametag.co/people/bulk \
  -d '{
  "requests": [
    {
      "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
      "scopes": [
        "nt:email",
        "nt:legal_name"
      ]
    }
  ]
}'
{
  "data": [
    {
      "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
      "properties": [
        {
          "expires": 1637321520,
          "scope": "nt:email",
          "value": "alice@example.com",
          "status": 200
        },
        {
          "expires": 1637321520,
          "scope": "nt:legal_name",
          "value": "Alice Smith",
          "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:

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.

Example:

$ curl -u :$APIKEY \
  -X POST \
  https://nametag.co/people/$SUBJECT/compare \
  -d '{
  "expectations": [
    {
      "scope": "nt:legal_name",
      "value": "Alice Smith",
    }
  ]
}'

{
  "confidence": 0.9,
  "comparisons": [
    {
      "scope": "nt:legal_name",
      "expected": "Alice Smith",
      "value": "Alice Catherine Smith",
      "match_confidence": 0.96,
      "match": true
    }
  ]
}

Compare selfie

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

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.

For the best results, please upload a photo that is within these parameters:

• the photo has only one face in it
• the overall scene in the photo is not too dark or too bright
• the image file size should not exceed 5MB
• the image file dimensions should be at least 100x100 pixels per side on the image but no larger than 10,000 pixels per side
• for images that are larger than 100 by 100 pixels, the face should occupy at least 100x100 pixels

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:

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.

Note: You must validate the raw bytes of the request body before you parse the JSON content. Any minor changes to whitespace, field order, or new fields will cause the signature validation to fail.

Example: Verifying the signature on the command line.

WEBHOOK_SHARED_SECRET="webhook-683fb6598c7faa4f05e4e693d3686f5faa6b9cd7bb646c5254edd3cb880f4225"
X_NAMETAG_SIGNATURE="e51e995e66aabc85f5f15f3c9dcdf859757aa117fd7ab13ccb61c54057d744f3"
ACTUAL_SIGNATURE=$(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" |\
  awk '{print $2}')
if [ "$ACTUAL_SIGNATURE" = "$X_NAMETAG_SIGNATURE" ]; then
  echo "Signature matched, process request"
else
  echo "Signature did not match, reject request"
fi

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:

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"
  ]
}

Revoke event

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

Event type: revoke

Request body:

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

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"
  ]
}

Recover event

This event is emitted just before a person recovers an account using a connected directory service such as Entra ID or Okta.

Event type: recover

Request body:

Response body: (optional)

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",
  "language": "en-US,en;q=0.9",
  "directory": "132bf0fb-55dd-4b19-ad54-e43a85c8bd50",
  "external_id": "alice@example.com",
  "action": "reset-password",
  "env_name": "My Environment",
  "org_name": "My Company"
}

Rejecting a recovery operation

Unlike the other webhooks, Nametag can optionally process the response your server sends to from the webhook. This allows you implement logic to prevent us from performing a recovery operation. This process looks like this:

To reject the recovery operation your webhook handler must:

• Respond with an HTTP status code of 200
• Set the Content-type response header to application/json
• The response body must contain a valid JSON document like:

The deny_user_message field is a user-facing message that will be displayed to the user. If this field is absent or null, then Nametag assumes that you want to allow the recovery to continue. If you serve users in multiple languages, use the language field of the request to determine how deny_user_message should be translated.

Request event (beta)

This event is emitted whenever a request changes status. It contains the same information as the get request endpoint.

Event type: request

Request body:

The event_type field will have one of the following values:

Accounts API

An account represents a user entry in a directory. Accounts are created from the directory synchronization process, which runs automatically every hour, or when you press the “Sync Now” button in the console.

List Accounts

Method: GET

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

Authentication: API key

Response:

Each item in accounts is an object consisting of:

An AccountPhoto is an object with the following fields:

Get an account

Fetches a single account. The ACCOUNT-ID can be either the id, one of the directory_identifiers or directory_immutable_identifier for the account.

Method: GET

URL: https://nametag.co/api/accounts/ACCOUNT-ID

Authentication: API key

Response: Account

{
  "id": "f3a579f8-bf03-4d1d-a582-b9ff801d0ab5",
  "directory_identifiers": ["alice@example.com"],
  "directory_immutable_identifier": "1904df08-b3b2-41b3-80d9-52cea873f62a",
  "name": "Alice Smith",
  "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
  "birth_date": "1989-12-13",
  "photo": {
    "sha256": "324a68d4a6185dd91a77c13950eb93853c9b00752ad072c248f96643b1289f4e",
    "created_at": "2023-07-10T14:03:13Z"
  }
}

Update an account

Updates an account. The ACCOUNT-ID can be either the id, one of the directory_identifiers or directory_immutable_identifier for the account.

Method: PATCH

URL: https://nametag.co/api/accounts/ACCOUNT-ID

Authentication: API key

Request:

All fields of the request are optional. If you omit a field, it will not be changed. The request may contain the following fields:

Response: none

Add a photo

Adds a photo to an account. The ACCOUNT-ID can be either the id, one of the directory_identifiers or directory_immutable_identifier for the account.

Method: PUT

URL: https://nametag.co/api/accounts/ACCOUNT-ID/photo

Authentication: API key

Request: JPEG image

This request will fail if the account is already bound to a subject and that person’s provided selfie does not match the photo you upload. It will also fail if the photo is not a valid JPEG image, or does not contain exactly one legible face.

Note: Photos must not be larger than 7MB

Bulk update accounts

Method: PATCH

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

Authentication: API key

Request:

An AccountBulkUpdateRequestItem is an object with the following fields:

Response:

An AccountBulkUpdateResponseItem is an object with the following fields:

A AccountBulkUpdateStatus is one of the following values:

Bulk photo upload

Adds multiple photo to an account.

Method: POST

URL: https://nametag.co/api/account/photos

Authentication: API key

Query parameters:

Request: Zip archive containing JPEG or PNG images

You must provide a zip archive. Each file in the zip archive should be named as ACCOUNT-ID.jpeg or ACCOUNT-ID.png. The ACCOUNT-ID can be either the id, one of the directory_identifiers or directory_immutable_identifier for the account. Each image will be associated with an existing account in the same manner as the Add photo endpoint above.

Note: The uploaded file may not be larger than 500MB. Split your bulk imports into parts and call this API repeatedly if you need to upload more than 500MB worth of images.

Response:

Example:

$ ls bulk
alice@example.com.jpg
bob@example.com.jpg
charlotte@example.com.jpg
danielle@example.com.jpg
ed@example.com.jpg

$ zip -r bulk.zip bulk

$ curl -u :$APIKEY \
  https://nametag.co/api/account/photos?directory=b8e62529-a26f-4f2e-b4c4-b78ef85e75d6 \
  --upload-file bulk.zip
{
  "files": [
    {
      "filename": "bulk/alice@example.com.jpg",
      "account_id": "6572dcdd-c3e4-4e7b-b59a-a4ef25a613cb",
      "directory_identifiers": [
        "alice@example.com"
      ],
      "directory_immutable_identifier": "ffbb4ab9-c5ae-47c2-916b-35212115285b",
      "status": 200
    },
    {
      "filename": "bulk/bob@example.com.jpg",
      "account_id": "48b6f6fa-1ad8-4d53-861a-cdfd5c0e3376",
      "directory_identifiers": [
        "bob@example.com"
      ],
      "directory_immutable_identifier": "8eca86c8-cee7-4eda-98e2-c89cbef25f6c",
      "status": 200
    },
    {
      "filename": "bulk/charlotte@example.com.jpg",
      "account_id": "086b62c8-05cc-4895-a58b-caada9d10074",
      "directory_identifiers": [
        "charlotte@example.com",
        "charlotte@example.net",
      ],
      "directory_immutable_identifier": "27c97d75-01ce-4fd0-ad66-743c87574725",
      "status": 200
    },
    {
      "filename": "bulk/danielle@example.com.jpg",
      "status": 404,
      "error": "account not found"
    },
    {
      "filename": "bulk/ed@example.com.jpg",
      "account_id": "ef5deae7-1f2c-48a7-b1f1-70d8ddda75c7",
      "directory_identifiers": [
        "ed@example.com"
      ],
      "directory_immutable_identifier": "17937a5a-484f-488d-935b-67b919b8cc29",
      "status": 200
    }
  ]
}

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.

Organization

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:

Example:

$ curl -u :$APIKEY https://nametag.co/api/org
{
  "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:

Each ORG-MEMBER is an object consisting of:

The Role enumeration has one of the following values:

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:

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:

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

Response: none

Environment

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

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

The type EnvStorage defines the configuration of enterprise data custody. It contains the following fields:

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:

TemplateScopeDefinition

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

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:

Example:

$ curl -u :$APIKEY https://nametag.co/api/envs
{
  "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:

Example:

$ curl -u :$APIKEY \
    -X POST \
    https://nametag.co/api/envs
{
  "id": "x0n8vfkfcmh3ks"
}

Get

Fetch the settings for an environment.

Method: GET

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

Authentication: API key

Response: an Env object

Example:

$ curl -u :$APIKEY https://nametag.co/api/envs/x0n8vfkfcmh3ks
{
  "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.

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"]
    }
  ]
}'

Update the logo

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

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:

Response:

Example:

$ curl -u :$APIKEY \
  -X POST \
  https://nametag.co/api/envs/x0n8vfkfcmh3ks/templates \
  -d '{"name": "Transaction Authorization"}'
{"id": "a7da6fc2-ba44-44df-a863-3ac9f58b5ba6"}

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:

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

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/directories

Request:

Response:

List

Fetches information about each directory

Method: GET

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

Response:

• 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/directories/DIRECTORY-ID

Request: none

Response: none

Synchronize

Trigger synchronization of the directory.

Note: Synchronization happens automatically once per hour.

Method: POST

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

Request: none

Response: none

Authorize

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

Method: GET

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

Request: none

Response:

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:

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

Example:

$ curl -u :$APIKEY https://nametag.co/api/apikeys
{
  "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.

Method: POST

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

Authentication: API key

Request:

Response:

Example: Creating a global API key

curl -u :$APIKEY \
  -X POST \
  https://nametag.co/api/apikeys \
  -d '{
  "name": "Staging API Key",
  "role": "admin",
  "enabled": true
}'
{
  "id": "3p0wjj3b7vyia5",
  "key": "3p0wjj3b7vyia5V2JCNoO3TqHpjT"
}

Example: Creating an environment-scoped API key

curl -u :$APIKEY \
  -X POST \
  https://nametag.co/api/apikeys \
  -d '{
  "name": "Staging API Key",
  "envs": ["obo0jukwhhlbo8"],
  "role": "user",
  "enabled": true
}'
{
  "id": "3p0wjj3b7vyia5",
  "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: an APIKey object

curl -u :$APIKEY \
  https://nametag.co/api/apikeys/3p0wjj3b7vyia5
{
  "id": "3p0wjj3b7vyia5",
  "envs": ["obo0jukwhhlbo8"],
  "name": "Staging API Key",
  "created_at": "2022-03-15T22:39:59Z",
  "role": "user",
  "enabled": true
}