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 app.

Apps

Each user of the Nametag API creates one or more apps which are the basic unit of privacy separation. This means that anything a person shares with an app is kept private from another. Most people will create one App each for their production, staging, and development environments.

Scopes

Scopes are used to describe the information you want people to share with your app. In order to request a scope you must first define it in your app and provide additional parameters, such as what type of data, how long you need the data, and how you’ll use it. This is done separately for each App 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: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:covid_vaccine COVIDVaccineValue Information about their COVID vaccination status
nt:covid_card COVIDVaccineValue Information about their COVID vaccination status, including a URL to the image of the evidence they provided.
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 to your app. 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.)

Because each App is it’s own privacy domain, different apps will be issued with different subjects for the same person.

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

Teams

Teams are the unit of access control for you and your colleagues. Each Team contains one or more Apps. Each team has members (your colleagues) and can be assigned to roles (owner, administrator, or read-only access) within the team.

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:

Client ID and Secret

When using the People API to fetch and manage data shared with your app, you will mostly use a client ID and secret to authenticate.

This method uses HTTP basic authentication where the CLIENT_ID is the username and the CLIENT_SECRET is the password. Each app has it’s own CLIENT_ID and CLIENT_SECRET which you can get from the developer console.

$ curl -u "CLIENT_ID:CLIENT_SECRET" \
    https://nametag.co/api/people/SUBJECT/nt:name,nt:age_over_21

ID Token

An ID token authenticates a particular person, rather than your entire app. This is returned from the token endpoint. You can only use ID tokens to fetch information about a single user only and you must use the URL /api/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/api/people/me/nt:name

API Key

API keys are used to manage teams and apps. Get an API key from the developer console. To use an API key, use HTTP basic authentication with an empty username and the API_KEY as the password.

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

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 data from people when they are on the web or mobile. This API is based on OAuth 2.0 so many standard OAuth 2.0 libraries will work with this interface.

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.

Request authorization

To request information from a user, direct their browser to the Nametag authorization endpoint.

Method: GET

URL: https://nametag.co/authorize

Authentication: none

Query parameters:

Parameter Description
client_id Your app’s client 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 App’s callback_urls list.
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.

Example: (whitespace added for clarity)

https://nametag.co/authorize?
  client_id=6f9434c1-4f0b-45dc-98c5-6224f1c23459&
  scope=nt%3Aemail+nt%3Aname+nt%3Alegal_name&
  state=83f4e159-5cab-4002-ac5a-809f21925a67&
  redirect_uri=https%3A%2F%2Fexample.com%2Fcallback

Completing authorization

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

Parameter Description
state The arbitrary data you provided to /authorize.
code A code which you can use with 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: Specify CLIENT-ID and CLIENT-SECRET in the body of the message

Request: An HTML form with the following parameters

Parameter Description
grant_type must be authorization_code
client_id Your app’s client ID.
client_secret Your app’s client secret.
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 to your app. This is a good candidate for storing in a database to track a particular user. A subject issued to one app has no meaning to any other app.

Example: (whitespace added for clarity)

Request:

$ curl https://nametag.co/token \
   -d grant_type=authorization_code \
   -d client_id=6f9434c1-4f0b-45dc-98c5-6224f1c23459 \
   -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.

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 clip, instant app, or full mobile app (if installed).

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

Method: POST

URL: https://nametag.co/requests

Authentication: API key

Request: A JSON object with the following fields:

Field Type Meaning
app string The ID of the app associated with the request
scopes list of string An array of scopes to request
phone string (optional) A phone number that will receive an authorization link via SMS

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.

Example:

$ curl -u :$APIKEY \
  -X POST \
  https://nametag.co/api/requests \
  -d '{
    "app": "tp7975e07n8sjl",
    "scopes": ["nt:phone", "nt:legal_name"],
    "phone": "+12025551212"
}'
{
  "id": "32478070-6fc9-4b26-8f2c-5269f1222c6f",
  "status": 100,
  "scopes": ["nt:phone", "nt:legal_name"],
  "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/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
status number The status code for the request. The value of 100 (the request is pending), 200 (the request has been accepted) or 403 (the request was rejected).
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.

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"],
  "link": "https://nametag.co/i/utl2ffahuw7lqf"
  "subject": "ewyzkwmoor5xg5ead2zjswudjq@5lsqfg1luqzb9s.nametag.co"
}

Cancel a request

Aborts 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.

Method: DELETE

URL: https://nametag.co/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

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: Client secret is available for any subject. ID token is available as long as the token matches the subject you are requesting, or is the special subject 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, ... ]
}

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 has expired.

Errors:

  • 400 Bad Request - The one or more of the scopes requested are invalid or not registered with your app.

Example:

$ CLIENT_ID=6f9434c1-4f0b-45dc-98c5-6224f1c23459
$ CLIENT_SECRET=ed1227ffbd35ff2b83bc8bd2c6af6473e596be875f094ef08da6a3c041d584f0
$ SUBJECT=vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co
$ curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  "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
    }
  ]
}

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 app’s access to a scope at any time. Less commonly, your app 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: Client secret is available for any subject. ID token is available as long as the token matches the subject you are requesting, or is the special subject 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.

Request: none

Response: none

Example:

CLIENT_ID=6f9434c1-4f0b-45dc-98c5-6224f1c23459
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: Client secret

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:

CLIENT_ID=6f9434c1-4f0b-45dc-98c5-6224f1c23459
CLIENT_SECRET=ed1227ffbd35ff2b83bc8bd2c6af6473e596be875f094ef08da6a3c041d584f0
curl 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 we support is nt:legal_name.

Method: POST

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

Authentication: Client secret

Request body:

{
  "expectations": [
    {
      "scope": "nt:legal_name",
      "value": "First Last",
    },
  ]
}

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 value of the scope that is returned from the GET property 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
    }
  ]
}

Webhooks

Webhooks allow your app to handle events initiated by Nametag. When events of interest occur, our service will make an HTTPS request to your app. Webhooks are configured on a per-app 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 app 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 we recommend Let’s Encrypt

Share event

This event is emitted whenever a person shares information with your app.

Event type: share

Request body:

{
  "event_type": "share",
  "subject": "SUBJECT",
  "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: a2053d3c5981abb85600b9176b4c251d4a5056270a95e53be3bfbf4929c4a563

{
  "event_type": "share",
  "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
  "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",'\
    '"scopes":["nt:email","nt:name","nt:legal_name"]}' |\
  openssl dgst -sha256 -hmac "$WEBHOOK_SHARED_SECRET"
a2053d3c5981abb85600b9176b4c251d4a5056270a95e53be3bfbf4929c4a563

Revoke event

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

Note: this event is not emitted when access expires, or when you call delete properties, only when a user actively revokes access in the Nametag app.

Event type: revoke

Request body:

{
  "event_type": "revoke",
  "subject": "/* the person's subject */",
  "scopes": ["nt:name", "nt:age_over_21"]
}

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",
  "scopes": [
    "nt:email",
    "nt:legal_name",
    "nt:name"
  ]
}

Data types

COVID Vaccination

When fetching a property with the scope nt:covid_vaccine or nt:covid_card, the data returns is a JSON object with the following structure:

Field Type Description
status string The vaccination status of the person. One of: peak meaning that they are fully vaccinated, partial meaning that they have received at least one vaccine dose, or that they have received the required number of doses but that not enough time has passed for the vaccine to be fully effective.
manufacturer string The type of vaccine they received. Possible values are pfizer, moderna, jj, oxford, novavax, covishield, sinovac, sinopharm, sputnik, and covaxin.
dose1_date RFC 3339 full-date The date of their first dose
dose2_date RFC 3339 full-date The date of their second dose. If they have not received a second dose, then this value is an empty string.
booster_date RFC 3339 full-date The date of their booster dose. If they have not received a booster dose, then this value is an empty string. Booster doses do not affect the immunity calculation in status.
peak_immunity_after RFC 3339 full-date The date after which the person will be considered to have peak immunity status.
validated boolean This value is true if the vaccine evidence provided has been verified to match the information provided. If this value is false is means that the person has attested to the information but it has not yet been verified. This is most likely to occur when a person has presented non-standard vaccination evidence that must be manually validated. Manual validations usually take no more than a few hours.
evidence_image_url string Present only for the nt:covid_card scope. A URL that contains an image of the evidence that the person submitted. This URL is valid for only a short time (several minutes) after the response is received from Nametag.

Configuration API

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

App

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

Field Type Description
id string The identifier for this app
team_id string The team identifier that owns this app
client_id string The OAuth 2.0 client ID
name string The internal name for this app, e.g. “Production”
public_name string The name of the app 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 app’s logo, which is displayed in the Nametag mobile app.
terms_of_service_url string A URL that points to your app’s terms of service or privacy policy, e.g. https://example.com/privacy. This is linked in the Nametag mobile app.
scopes list of AppScopeDefinition Defines which scopes your app will request.
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 AppWebhook A list of webhooks.

AppScopeDefinition

The type AppScopeDefinition defines a scope that your app may request.

Field Type Description
scope string The scope that your app will request.
expires_in integer How long will data for the scope be valid, in seconds.
reason string English text that describes the purpose of requesting this scope.
priority integer Specifies the order of this scope when listed in the mobile app. Lower values are listed first.
restrict_email_domains list of string For the nt:email scope only, require that each value be in the specified domain.

AppWebhook

The type AppWebhook defines a webhook for an app. It contains the following fields:

Field Type Description
url string The URL in your app 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.

List apps

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

Method: GET

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

Authentication: API key

Response:

{
  "apps": [ APP, ... ]
}

Example:

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

Response:

{
  "apps": [
    {
      "id": "5lsqfg1luqzb9s",
      "team_id": "tp7975e07n8sjl",
      "client_id": "6f9434c1-4f0b-45dc-98c5-6224f1c23459",
      "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",
      "scopes": [
        {
          "scope": "nt:name",
          "expires_in": 86400,
          "reason": "",
          "priority": 0,
          "restrict_email_domains": null
        },
        {
          "scope": "nt:email",
          "expires_in": 86400,
          "reason": "",
          "priority": 0,
          "restrict_email_domains": null
        },
        {
          "scope": "nt:legal_name",
          "expires_in": 86400,
          "reason": "",
          "priority": 0,
          "restrict_email_domains": null
        }
      ],
      "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 app

Method: POST

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

Authentication: API key

Request:

{
  "team": "TEAM-ID"
}

Response:

{
  "id": "APP-ID"
}

Example:

$ curl -u :$APIKEY \
    -X POST \
    https://nametag.co/api/apps  -d '{
      "team": "tp7975e07n8sjl"
    }'

Response:

{
  "id": "x0n8vfkfcmh3ks"
}

Get

Fetch the settings for an app.

Method: GET

URL: https://nametag.co/api/apps/APP-ID

Authentication: API key

Response: an App object

Example:

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

Response:

{
  "id": "5lsqfg1luqzb9s",
  "team_id": "tp7975e07n8sjl",
  "client_id": "6f9434c1-4f0b-45dc-98c5-6224f1c23459",
  "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",
  "scopes": [
    {
      "scope": "nt:name",
      "expires_in": 86400,
      "reason": "So we can address you in our app and on the web.",
      "priority": 20
    },
    {
      "scope": "nt:email",
      "expires_in": 86400,
      "reason": "So we can send you updates about your Sidecar account",
      "priority": 10
    },
    {
      "scope": "nt:legal_name",
      "expires_in": 86400,
      "reason": "So we know you are a real person",
      "priority": 30
    }
  ],
  "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 app. All the request fields are optional, and only fields that are provided will be changed.

Method: PATCH

URL: https://nametag.co/api/apps/APP-ID

Authentication: API key

Request:

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

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

To modify a scope or webhook, include both the remove_* and add_* in the same request. For example, to replace an AppScopeDefinition, include both remove_scopes and add_scopes in your request.

Example:

$ curl -u :$APIKEY https://nametag.co/api/apps/x0n8vfkfcmh3ks -X PATCH -d '{
  "name": "Example app",
  "remove_scopes": ["nt:name"],
  "add_scopes": [
    {
      "scope": "nt:name",
      "expires_in": 3600,
      "reason": "So we can address you",
      "priority": 23
    }
  ]
}'

Update the client secret

Generates a new client secret replacing any existing client secret.

Important: Make sure you save the value returned from this API. It can only be returned to your app once.

Method: POST

URL: https://nametag.co/api/apps/APP-ID/client_secret

Authentication: API key

Response:

{
  "client_secret": "..."
}

Example:

$ curl -u :$APIKEY \
  -X POST \
  https://nametag.co/api/apps/x0n8vfkfcmh3ks/client_secret

Response:

{
  "client_secret": "52985463afb3e8349328ccc9a35a8eab9f4750c7a15af18cde349cb3aee5812d"
}

Method: POST

URL: https://nametag.co/api/apps/APP-ID/logo

Authentication: API key

Request: A PNG, SVG, or JPEG of your app’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/apps/x0n8vfkfcmh3ks/logo

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

Remove

Remove an app.

Method: DELETE

URL: https://nametag.co/api/apps/APP-ID

Request: none

Response: none

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

Teams

A team is a container for your Apps. Each team has members, which are people that have access to management information about your apps.

List

List the teams that you have access to.

Method: GET

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

Authentication: API key

Response:

{
  "teams": [
    {
      "id": "...",
      "name": "Acme Corp",
      "role": "owner"
    }
  ]
}

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

Field Type Description
id string The unique identifier for the team
name string The name of the team
role string Your role on the team, which is either owner, admin or reader.

Example:

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

Response:

{
  "teams": [
    {
      "id": "tp7975e07n8sjl",
      "name": "Acme Corp",
      "role": "owner"
    }
  ]
}

Create

Create a new team. This request takes the name of the new team to create and returns a unique identifier for the newly created team.

Note: Team names are internal. Only team members see the name of a team.

Method: POST

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

Authentication: API key

Request:

{
  "name": "Acme Corporation"
}

Response:

{
  "id": "team ID"
}

Example:

$ curl -u :$APIKEY \
  https://nametag.co/api/teams \
  -d '{"name": "Acme Corporation"}'

Response:

{"id":"7kpb46mqpduu36"}

Get

Fetch information about a team

Method: GET

URL: https://nametag.co/api/teams/TEAM-ID

Authentication: API key

Request: none

Response:

{
  "id": "APP-ID",
  "name": "Acme Corp",
  "role": "owner"
}

List members

Returns a list of the current members of a team

Method: GET

URL: https://nametag.co/api/teams/TEAM-ID/members

Authentication: API key

Request: none

Response:

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

Each TEAM-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 team.
role string The person’s role on the team. 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 team (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 a team

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

Method: POST

URL: https://nametag.co/api/teams/TEAM-ID/members

Authentication: API key

Request:

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

Response: none

Remove a team member

Removes a person from a team.

Method: DELETE

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

Authentication: API key

Request: none

Response: none

Set the a team member’s role

Assign a role to a team member

Method: PATCH

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

Request:

{
  "role": "admin"
}

The role must be one of reader, admin , or owner. There can be at most one person in a team marked as owner.

Response: none

API Keys

As mentioned in Authentication above, API keys are used to manage teams and apps.

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",
      "team_id": "k2mb4yifkaqo5s",
      "name": "Staging API Key",
      "created_at": "2022-03-15T22:39:59Z",
      "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
team_id string The unique identifier for the team this API key belongs to
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",
      "team_id": "k2mb4yifkaqo5s",
      "name": "Staging API Key",
      "created_at": "2022-03-15T22:39:59Z",
      "enabled": true,
    }
  ]
}

Create

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

Note: API key names are internal. Only team members see the name of an API Key.

API keys are 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:

{
  "name": "Staging API Key",
  "team_id": "k2mb4yifkaqo5s",
}

Response:

{
  "key": "3p0wjj3b7vyia5V2JCNoO3TqHpjT"
}

Example:

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

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",
  "team_id": "k2mb4yifkaqo5s",
  "name": "Staging API Key",
  "created_at": "2022-03-15T22:39:59Z",
  "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. ↩︎ ↩︎ ↩︎ ↩︎