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) |
expires_at |
RFC 3339 date-time | The time at which the request is no longer valid (e.g. `2024-04-14T00:00:00Z) |
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"],
"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:
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 |
ticket |
string | The request ticket (used to construct the link) |
link |
string | The URL which should be send to the user. This link launches the mobile app and prompts the user to verify their identity. |
phone |
string (optional) | The phone number that will receive an authorization link via SMS |
env |
string | The ID of the environment associated with the request |
template |
string (optional) | The ID of the template used for this request |
label |
string (optional) | The label for the request; can be empty |
scopes |
list of string | An array of the scopes that were requested |
status |
string | The status of the request. Possible values are in_progress , shared , revoked , cancelled , expired , expired_scopes , rejected_appealed , rejected_unusable , and rejected_fraud . |
progress |
string | Indicates the user’s progress through the scanning process. Possible values are created , link_opened , app_opened , id_scanned , face_scanned , and consent_given . |
subject |
string (optional) | The subject of the request. Present only when status is shared . Use this as a parameter to the properties endpoint to fetch the data shared. |
subject_text |
string (optional) | A description of the subject (e.g. their name or email address) suitable for presentation in a user interface. |
requester |
string (optional) | The member ID of the user that created this request. This field is absent for requests created via the API |
requester_text |
string (optional) | A description of the requester suitable for presentation in a user interface (e.g. their name or email address) |
properties |
RequestProperties (optional) | The properties that were shared with you. |
mobile |
RequestMobileDevice (optional) | Details of the end-user’s mobile device |
browser |
RequestBrowser (optional) | Details of the browser used to pivot to the mobile app (present for only some flows). |
details |
RequestDetails (optional) | Details of the ID scan process associate with this person. Only present when the caller’s role is >= user and the organization is on the Enterprise plan |
RequestProperties
The type RequestProperties
has the following fields:
Field | Type | Meaning |
---|---|---|
phone |
string (optional) | Phone number, in E.164 format, e.g +1 202 555-1212 |
legal_name |
string (optional) | The person’s name from their identity document |
legal_first_name |
string (optional) | The given name (first name) from their identity document 2 |
legal_last_name |
string (optional) | The family name (last name) from their identity document 2 |
name |
string (optional) | The person’s preferred name 1 |
first_name |
string (optional) | The person’s preferred given (first) name 2 |
last_name |
string (optional) | The person’s preferred family (last) name 2 |
birth_date |
RFC 3339 full-date (optional) | The person’s date of birth |
email |
string (optional) | Verified email address |
unverified_email |
string (optional) | The email address provided by a user but not verified |
age_over_18 |
boolean (optional) | true if the person is over 18 years old, otherwise false |
age_over_21 |
boolean (optional) | true if the person is over 21 years old, otherwise false |
profile_picture |
URL (optional) | 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. |
address |
string (optional) | Verified postal address |
govtid_details |
GovtidDetailsValue (optional) | Additional information about the identity document presented by the user |
GovtidDetailsValue
The type GovtidDetailsValue
has the following fields:
Field | Type | Meaning |
---|---|---|
type |
string (optional) | The type of the identity document. Possible values are passport , driver_license , or other |
issuer |
string (optional) | The issuer of the identity document, an ISO 3166-1 alpha 3 country code optionally followed by a jurisdiction code, e.g. USA.CA or CAN.ON |
number |
string (optional) | The unique number of the identity document |
expiration |
RFC 3339 full-date (optional) | The date when the identity document expires |
RequestMobileDevice
The type RequestMobileDevice
has the following fields:
Field | Type | Meaning |
---|---|---|
os |
string | The full operating system name and version of the mobile device |
version |
string | The verison of the Nametag app |
ios |
boolean | true if the device is an iOS device, otherwise false |
android |
boolean | true if the device is an Android device, otherwise false |
full_app |
boolean | true if the request was completed in the full Nametag app, otherwise false |
app_clip |
boolean | true if the request was completed in the iOS app clip, otherwise false |
instant_app |
boolean | true if the request was completed in the Android instant app, otherwise false |
remote_address |
string | The IP address of the mobile device (This field is null unless the nt:location:ip scope is specified in the request) |
remote_address_location |
Location | The location of the mobile device based on its IP address (This field is null unless the nt:location:ip scope is specified in the request) |
RequestBrowser
The type RequestBrowser
has the following fields:
Field | Type | Meaning |
---|---|---|
user_agent |
string | The browser’s user agent |
remote_address |
string | The IP address of the browser (This field is null unless the nt:location:ip scope is specified in the request) |
remote_address_location |
Location | The location of the browser based on its IP address (This field is null unless the nt:location:ip scope is specified in the request) |
RequestDetails
The documentation for this is available to all customers with an NDA in place. Please contact help@nametag.co for more information.
RequestAccount
The type RequestAccount
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:
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
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: none
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.
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.96,
"match": true
}
]
}
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,
"match": true
}
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.
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"
}
The recover
event, unlike the other webhooks, is asynchronous. That is, Nametag waits for a 200 OK
response from your webhook receiver before proceeding. This gives you the opportunity to use the data in the webhook to do additional processing at the receiver (outside of Nametag) and return a decision to Nametag that will allow the recover event to proceed or stop it from proceeding. This process looks like this:
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:
{
"event_type": "request",
"event": "EVENT",
"request": REQUEST
}
The REQUEST field contains the same information as the get request endpoint.
The EVENT is the reason that the webhook was fired. Possible values are request_created
, request_accepted
, request_rejected
, request_canceled
, request_app_opened
, request_email_selected
, request_link_opened
, request_selfie_verified
, request_label_changed
, request_oauth_code_issued
, request_oauth_token_issued
, scan_started
, scan_front_image_added
, scan_back_image_added
, scan_selfie_image_added
, scan_selfie_smile_added
, scan_aadhaar_added
, scan_finished
, scan_aborted
, scan_appealed
, scan_appeal_accepted
, scan_appeal_rejected
, scan_accepted
, scan_rejected
, biometric_consent
, end_user_revoke
, vendor_revoke
, vault_phone_added
, vault_phone_verified
, vault_phone_resent
, vault_phone_deleted
, vault_email_added
, vault_email_verified
, vault_email_resent
, vault_email_deleted
, vault_profile_picture_added
, vault_profile_picture_removed
, vault_preferred_name_set
, profile_picture_accepted
, profile_picture_rejected
, and vault_deleted
.
Note: The
event
field is provided for transparency about why the webhook is being emitted. The possible values ofevent
may change over time and are not part of the API contract. We recommend that you use the status information in therequest.progress
andrequest.status
fields to determine the current state of a request. Different user flows may result in certain events not being emitted, for example if the user has already scanned their ID thescan_*
events are not emitted. Therequest.status
field is your best source of truth.
Accounts
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
Method: GET
URL: https://nametag.co/api/accounts
Authentication: API key
Response:
{
"accounts": [ ACCOUNT, ... ]
}
Each ACCOUNT is an object consisting of:
Field | Type | Description |
---|---|---|
id |
string | The Nametag identifier for the account. |
directory_identifiers |
list of string | The identifiers for the account used by the directory (typically an email address, username) |
directory_immutable_identifier |
string | The unchanging identifier for the account used by the directory. Most directories have an UUID or other opaque identifier that doesn’t change even when directory_identifiers changes. |
name |
string | The person’s name, according to the directory |
subject |
string | The Nametag Subject for this person, if the account has been bound to a subject . Null otherwise. |
have_birth_date |
boolean | true if the person’s expected birth date has been set for the directory. |
photo |
AccountPhoto |
A verified photo of the person that you provide. If this field is set prior to being bound to a subject , then the selfie must match this photo. |
An AccountPhoto
is an object with the following fields:
Field | Type | Description |
---|---|---|
sha256 |
string | The SHA256 hash of the uploaded image. |
created_at |
RFC 3339 full-date | The time when the image was added. |
Get
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:
{
"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
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:
{
"subject": "SUBJECT",
"birth_date": "BIRTH_DATE"
}
All fields of the request are optional. If you omit a field, it will not be changed. The request may contain the following fields:
Field | Type | Description |
---|---|---|
subject |
string | The subject for this person. Set this to an empty string to remove the binding for this person. |
birth_date |
RFC 3339 full-date | The subject’s date of birth. If this is set prior to the account being bound to a subject , then the birth date on their ID must match this date. |
Response: none
Add 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 photo upload
Adds multiple photo to an account.
Method: POST
URL: https://nametag.co/api/account/photos
Authentication: API key
Query parameters:
Parameter | Description |
---|---|
directory |
Required The ID of the directory to associate photos with. |
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:
{
"files": [
{
"name": "Alice@Example.Com.jpg",
"directory_identifiers": ["alice@example.com"],
"directory_immutable_identifier": "1904df08-b3b2-41b3-80d9-52cea873f62a",
"status": 200
},
{
"name": "missing@example.com.jpg",
"directory_immutable_identifier": "6dc17dd2-6688-4fb6-a396-cda49eee8e6d",
"status": 404,
"error": "cannot find account"
},
{
"name": "bob@example.com.jpg",
"directory_identifiers": ["bob@example.com"],
"directory_immutable_identifier": "c851e693-0c6c-4f71-a429-f2f0fc57cdde",
"status": 422,
"error": "image contains more than one face"
},
{
"name": "christine@example.com.jpg",
"directory_identifiers": ["christine@example.com"],
"directory_immutable_identifier": "",
"status": 422,
"error": "image does not contain any faces"
},
{
"name": "david@example.com.jpg",
"directory_identifiers": ["david@example.com"],
"directory_immutable_identifier": "4d307709-ee87-44a0-8253-d831f0754a85",
"status": 400,
"error": "image does not match previous selfie"
}
]
}
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.
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"]
}
]
}'
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
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
}
-
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. ↩︎ ↩︎
-
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. ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎