API Reference

Overview

The Nametag API contains several parts:

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

Claims

Claims are used to describe the individual user attributes you want people to share with you. Nametag supported claims are a mix of those defined in the OIDC standard and those unique to Nametag.

The following claims are defined:

Claim enum
`name`	The person's name from their identity document
`given_name`	The given name (first name) from their identity document
`family_name`	The family name (last name) from their identity document
`preferred_name`	The person's preferred name
`phone_number`	Phone number, in E.164 format, e.g `+1 202 555-1212`
`address`	Verified postal address
`birth_date`	The person's date of birth (an RFC 3339 full-date)
`govtid`	Details about the person's identity document, a JSON-encoded GovtidValue
`govtid_expired`	`true` if we have a govtid expiration date and it is past that date; `false` if we either can't get an expiration date or it is not expired.
`picture`	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.
`account`	The person's Nametag account information, a JSON-encoded AccountValue
`email`	The person's email validated against their Nametag account

The `Email` claim

The Email claim validates a person’s email by matching the person’s identity to an account in a connected directory (e.g. Entra ID, Okta, etc). The policy used to evaluate the binding is:


`name_match`	The operation can proceed if the name on the account matches the person's legal name. If the Account is augmented with a birthdate, then the birthdate must match. If the account is augmented with a photo, then only the photo must match.

Note: When requesting this claim, the *CLIENT_ID* used in the flow must be *DIRECTORY_ID* of a directory where the account to be matched is found. *DIRECTORY_ID* is found in the Nametag console on the settings page of a connected directory.

The `Account` claim

account is a Nametag-specific claim that matches the person’s identity to an account in a connected directory (e.g. Entra ID, Okta, etc). It is a JSON object of type AccountValue and has the following fields:

AccountValue struct
`immutable_external_id`string (optional)	A GUID that uniquely identifies this entry in the directory, even if the external IDs change
`ids`List of string (optional)	The list of ID's associated with the account
`binding_strength`string (optional)	The binding strength used to determine account info

Note: When requesting this claim, the *CLIENT_ID* used in the flow must be *DIRECTORY_ID* of a directory where the account to be matched is found. *DIRECTORY_ID* is found in the Nametag console on the settings page of a connected directory.

You can request a specific binding strength based via using the account claim in the claims request parameter. The supported binding strengths are:


`name_match`	The operation can proceed if the name on the account matches the person's legal name. If the Account is augmented with a birthdate, then the birthdate must match. If the account is augmented with a photo, then only the photo must match.
`name_and_birth_date`	The operation can proceed if both the name and birthdate match between the Account and the person's ID. If the account is augmented with a photo, then only the photo must match.
`photo`	The operation can only proceed if the account is augmented with a photo and the photo matches the person's ID.

If a binding strength is not requested via a claims parameter then default name_match is applied. If the identity cannot be matched to an account, the account claim will not be present in the id_token. If this happens, the id_token contains an account_status claim which describes the reason for the failure. The AccountStatus claim is a JSON object and has the following fields:

AccountStatus
`failure_reason`string	The reason for binding failure

Scopes

Scopes are a set of user attributes that you can request. Nametag implements scopes as defined in the OIDC standard.

Scope enum
`openid`	A required scope, used to indicate that the application intends to use OIDC to verify the user's identity

Subject

A subject uniquely identifies a person. You should 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 in 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. By 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 over HTTPS. Unless otherwise noted, all requests and responses are JSON-encoded and use the application/json content type.

Authentication

Use API keys to authenticate requests to the Nametag API. Get an API key from the Nametag console. Each API key is scoped to either work for some or all of your environments, depending on your needs.

To use an API key provide the Authorization header:

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

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, so many standard OAuth libraries will work with this interface.

Create authorization

To initialize a request, the /oauth2/par endpoint needs to be used. This will allow you to register the request with Nametag and get back a REQUEST_URI that can be used to in initiate the flow.

Method: POST

URL: https://nametag.co/oauth2/par

Authentication: A valid client_secret provisioned in the OAuth section of the Nametag console.

Request: An HTML form with the following parameters

Parameter	Description
`client_id`	Your environment’s ID, from the Nametag console.
`client_secret`	The `client_secret` as provisioned in the OAuth section of the Nametag 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, must at least contain the `openid` scope.
`claims`	A JSON string indicating individual claims to be requested as specified by the OIDC spec. Note: Nametag only supports the `id_token` member.
`template`	The name of a pre-configured template to specify additional parameters for this request.
`expiry_seconds` (optional)	The value indicating how long the `request_uri` is valid for. Defaults to 60 seconds.
`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, for example `https://example.com/callback?code=CODE&state=STATE`. With `fragment` the response is passed after a hash, for example `https://example.com/callback#code=CODE&state=STATE`.
`email_hint` (optional)	The user’s email address, if you already know it.
`label` (optional)	An arbitrary label that will be attached to the Request

Response: A JSON object with the following fields:

Field	Meaning
`request_uri`	Used as a parameter to subsequent requests to `/oauth/authorize` to initiate the flow for the customer
`expires_in`	The number of seconds that the `request_uri` is valid for.

Example: In this case we are requesting the name claim without any specific value requirements

$ curl -X POST "https://nametag.co/oauth2/par" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=b34bxo33g6r3xv2" \
  -d "client_secret=hm25eexztk9qfumndR8CuxSbBPHwc" \
  -d "redirect_uri=http%3A%2F%2Flocalhost%3A9000%2Fcallback" \
  -d "state=b34bxo33g6r3xv2" \
  -d "scope=openid" \
  -d "claims=%7B%22id_token%22%3A%7B%22name%22%3Anull%7D%7D"

{
  "request_uri": "IH7A243DIR2GQGP34D4AFZVTYEECKXUHVGXQXHLVYBMMUVOYGNO6X534XE3TZYGWMNJ4PAPFFND52EMQIHYXYWCJOTLBWDVFJWXRLT32R5TZG2TEPB2PYSLMJPRYQYQ5HG5KKIEQXY======",
  "expires_in": 60
}

Request authorization

If your user has an active web session, or is active in your mobile app, direct their browser to the /oauth2/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/oauth2/authorize

Authentication: none

Query parameters:

Parameter	Description
`request_uri`	The value from the REQUEST_URI received in the previous step when the authorization was created

Example: (whitespace added for clarity)

https://nametag.co/authorize?
  request_uri=IH7A243DIR2GQGP34D4AFZVTYEECKXUHVGXQXHLVYBMMUVOYGNO6X534XE3TZYGWMNJ4PAPFFND52EMQIHYXYWCJOTLBWDVFJWXRLT32R5TZG2TEPB2PYSLMJPRYQYQ5HG5KKIEQXY======

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 OIDC 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/oauth2/token

Authentication: A valid client_secret provisioned in the OAuth section of the Nametag console.

Request: An HTML form with the following parameters

Parameter	Description
`grant_type`	must be `authorization_code`
`client_id`	The `client_id` as provisioned in the OAuth section of the Nametag console.
`client_secret`	The `client_secret` as provisioned in the OAuth section of the Nametag console.
`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 is a JSON Web Token (JWT) and when decoded, contains information about the user such as requested claims.
`expires_in`	The number of seconds that the authorization is valid for.
`subject`	This value uniquely identifies the person in your environment. A subject issued to one environment has no meaning to any other environment.

Example:

$ curl "https://nametag.co/token" \
   -d grant_type=authorization_code \
   -d client_id=obo0jukwhhlbo8 \
   -d client_secret=ef5f848e265eb423ee358cf12c5aef924c20d19356f7ad5aa07ad1614cfc4411 \
   -d code=09965885d2d8559d61b520935da550f7 \
   -d redirect_uri="https://example.com/callback"
{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvYXQiLCJleHAiOjE2MzcyMzg3MjUsImlhdCI6MTYzNzIzNTEyNSwiaXNzIjoibmFtZXRhZy5jbyIsIm5iZiI6MTYzNzIzNTEyNSwic3ViIjoidmtsamlwa2FpbzJhcDY2M2RvNTRyNWZwMmFANWxzcWZnMWx1cXpiOXMubmFtZXRhZy5jbyJ9.U2YAAc0TMnSJD_zKcCs_9Nayhrm5OdlcsjOQwbDSjOrBlAKI5uRCqXOoBB_oGjQjmWNYZhCYMUJShBPzSZfZZQ",
  "refresh_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvcnQiLCJleHAiOjIxNDc0ODM2NDcsImlhdCI6MTYzNzIzNTEyNSwiaXNzIjoibmFtZXRhZy5jbyIsIm5iZiI6MTYzNzIzNTEyNSwic3ViIjoidmtsamlwa2FpbzJhcDY2M2RvNTRyNWZwMmFANWxzcWZnMWx1cXpiOXMubmFtZXRhZy5jbyJ9.5D8lexomXYJoGZNDUFmxNB3TnQIhSDleb7kTL89VLHX30bilq95PDyJ5vE3W1IdmWGxziK9IE4puIkXxBEj7LA",
  "id_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJvaXQiLCJleHAiOjIxNDc0ODM2NDcsImlhdCI6MTYzNzIzNTEyNSwiaXNzIjoibmFtZXRhZy5jbyIsIm5iZiI6MTYzNzIzNTEyNSwic3ViIjoidmtsamlwa2FpbzJhcDY2M2RvNTRyNWZwMmFANWxzcWZnMWx1cXpiOXMubmFtZXRhZy5jbyJ9.P-elo7PUVC9dIBSV_UgoFbaHc2yATNOj8jumVTF_3izs9QqZ4lslvUsfCnogc1l7oEpowCR9d2j42J6J-5LWjw",
  "expires_in": 3600,
  "token_type": "Bearer",
  "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co"
}

Create a request

Creates a new request for information from a person.

Use this method when requesting information from people over the phone, in-person, or over 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.

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:

CreateRequestRequest struct
`env`string	The ID of the environment associated with the request.
`claims`List of Claim (optional)	A list of the information (claims) that the request is asking for. Note: This field is required unless `template` is specified.
`template`string (optional)	The name of a template that customizes how the request is presented to the user. Because a template contains its own claim definitions, you can provide either `claims` or `template`; providing both results in an amalgamation of the two.
`expires_at`RFC 3339 date-time string (optional)	The last time this request will be valid. After this time, the request is expired and the user will no longer be able to complete it. This cannot be used with `ttl`.
`phone`ITU E.184 phone number string (optional)	The phone number to which the request link should be sent.
`whatsapp`ITU E.184 phone number string (optional)	The WhatsApp phone number to which the request link should be sent.
`label`string (optional)	An internal label for this request. You can use this field to help you track the request in your own systems. Nametag stores this field, but does not process it at all.

Response: A JSON object with the following fields:

CreateRequestResponse struct
`id`string	A unique identifier for the request
`status`NumericRequestStatus	The status code for the request. Always `"pending"` when the request is initially created.
`env`string	The ID of the environment associated with the request.
`claims`List of Claim	A list of the information (claims) that the request is asking for.
`template`string (optional)	The name of a template that customizes how the request is presented to the user.
`link`string	An authorization link. Passing this link to the user will prompt them to complete the request.
`phone`string (optional)	The phone number to which the request link was sent, in E.164 format.
`label`string (optional)	An internal label for this request. You can use this field to help you track the request in your own systems. Nametag stores this field, but does not process it at all.
`expires_at`RFC 3339 date-time string (optional)	The last time this request will be valid. After this time, the request is expired and the user will no longer be able to complete it.

NumericRequestStatus enum
`410`
`403`
`404`
`100`
`101`
`200`
`550`
`551`
`552`
`411`

Example:

$ curl -u :$APIKEY \
  -X POST \
  https://nametag.co/api/requests \
  -d '{
    "env": "tp7975e07n8sjl",
    "claims": ["phone", "name"],
    "expires_at": "2024-04-14T06:34:00-07:00"
    "label": "Ref Customer #41471"
}'
{
  "id": "32478070-6fc9-4b26-8f2c-5269f1222c6f",
  "status": 100,
  "claims": ["phone", "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:

Request struct
`id`string	A unique identifier for this request
`created_at`RFC 3339 date-time string	Timestamp of when this request was created
`updated_at`RFC 3339 date-time string	Timestamp of the last time this request was updated
`expires_at`RFC 3339 date-time string	Timestamp of when this request expires
`ticket`string	The request ticket (used to construct the link)
`link`URL string	The URL which should be sent 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
`label`string	The label for the request; can be empty
`claims`List of Claim
`status`RequestStatus	The status of the request, e.g. `in_progress` or `shared`.
`progress`RequestProgress	Indicates the user's progress through the scanning process, e.g. `link_opened` or `id_scanned`.
`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	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 only for some flows).
`is_known_user`boolean (optional)	If the user is known as an account
`photo`string (optional)	The photo associated with this person
`external_ids`List of string (optional)	External IDs for accounts if the user is known
`marked_for_deletion_after`RFC 3339 date-time string (optional)	Indicates whether the person associated with this request has asked for their data to be deleted and the earliest time that will occur at.
`verification_source`RequestVerificationSource (optional)	Indicates how the user completed this request. This field is only present if the request has been shared.

`RequestStatus`

The enumeration RequestStatus can have the following values:

RequestStatus enum
`pending`	The request has been issued but the user has not yet opened the link.
`in_progress`	The user has opened the link but has not yet completed the request.
`shared`	The user has completed the request and authorized the data to be shared with you.
`revoked`	The user has authorized data sharing but then revoked the authorization.
`cancelled`	Either you or the user has cancelled the request
`person_deleted`	The user has deleted their Nametag
`expired`	The request has expired without the user having completed it
`expired_scopes`	The user has completed the request and authorized the data to be shared with you, but the sharing authorization has expired
`rejected_appealed`	The user has attempted to provide data, but the data was rejected and the user has appealed the decision. It is awaiting review by Nametag.
`rejected_unusable`	The user has attempted to provide data, but the data was rejected because the evidence submitted cannot be used.
`rejected_fraud`	The user has attempted to provide data, but the data was rejected because the data provided are fraudulent.

`RequestProgress`

The enumeration RequestProgress can have the following values:

RequestProgress enum
`created`	The link has been created but not yet opened.
`link_opened`	The link has been opened in a browser but the app has not yet been launched.
`app_opened`	The app has been launched.
`id_scanned`	The user has scanned their ID.
`face_scanned`	The user has scanned their face.
`consent_given`	The user has consented to sharing their data with you.

`RequestProperties`

The type RequestProperties has the following fields:

RequestProperties struct
`phone`ITU E.184 phone number string (optional)	The person's phone number
`name`string (optional)	The person's name from their identity document
`first_name`string (optional)	The person's given (first) name from their identity document
`last_name`string (optional)	The person's family (last) name from their identity document
`birth_date`RFC 3339 date string (optional)	The person's date of birth
`profile_picture`URL string (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`GovtidValue (optional)	Additional information about the identity document presented by the user
`govtid_Expired`boolean (optional)	`true` if we have a govtid expiration date and it is past that date; `false` if we either can't get an expiration date or it is not expired.
`account`AccountValue (optional)	The person's Nametag account information

`GovtidValue`

The type GovtidValue has the following fields:

GovtidValue struct
`type`GovtidType	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`
`document_number`string (optional)	The unique number of the identity document
`expiration`RFC 3339 date string (optional)	The date when the identity document expires

`GovtidType`

The enumeration GovtidType can have the following values:

GovtidType enum
`passport`	The user presented a passport.
`driver_license`	The user presented a driver license or similar card-based ID document.

`RequestMobileDevice`

The type RequestMobileDevice has the following fields:

RequestMobileDevice struct
`os`string	The full operating system name and version of the mobile device
`version`string	The version 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 (optional)	The IP address of the mobile device (This field is `null` unless the `location:ip` claim is specified in the request)
`remote_address_location`Location (optional)	The location of the mobile device based on its IP address (This field is `null` unless the `location:ip` claim is specified in the request)

`Location`

The type Location has the following fields:

Location struct
`business`boolean (optional)	Whether the location is a business.
`city`string (optional)	The city of the location.
`country`string (optional)	The country of the location.
`latitude`floating-point number	The latitude of the location.
`longitude`floating-point number	The longitude of the location.
`po_box`boolean (optional)	Whether the location is a PO box.
`residential`boolean (optional)	Whether the location is residential.
`subdivision`string (optional)	The subdivision of the location (e.g. the state or province).

`RequestBrowser`

The type RequestBrowser has the following fields:

RequestBrowser struct
`user_agent`string	The browser's user agent
`remote_address`string (optional)	The IP address of the browser (This field is `null` unless the `location:ip` claim is specified in the request)
`remote_address_location`Location (optional)	The location of the browser based on its IP address (This field is `null` unless the `location:ip` claim is specified in the request)

`RequestDetails`

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

Example: When the request is complete

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

Update a request

Method: PATCH

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

Authentication: API key

Request: A JSON object with the following fields:

UpdateRequestRequest struct
`label`string (optional)	An internal label for this request. You can use this field to help you track the request in your own systems. Nametag stores this field, but does not process it.

Response: none

Example:

$ curl -u :$APIKEY \
  -X PATCH \
  https://nametag.co/api/requests \
  -d '{
    "label": "updated label text"
}'

Cancel a request

Abort a request, invalidating the link for this request that was returned 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/*CLAIMS*

Authentication: API key.

Parameters:

SUBJECT - The subject you got back from the token endpoint which uniquely identifies the person.
CLAIMS - A comma-separated list of the claims you want to fetch.

Response:

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

The response contains the following fields:

PropertiesResponse struct
`subject`string	The subject of the request. This is the person whose properties are being requested.
`requests`List of PropertyResponseRequest	The requests that were made to get the properties.
`properties`List of PropertyResponse	Properties of the person.

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

PropertyResponse struct
`expires`RFC 3339 date-time string (optional)	When your access to this data expires
`claim`Claim	The Claim you requested.
`value`string (optional)	The value of the property. The type of this field varies depending on the claim. See this table.
`status`integer	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:

PropertyResponseRequest struct
`id`string	A unique identifier for the request.
`created_at`RFC 3339 date-time string	The time that the request was initiated
`status`integer	The status of the request, 200 means accepted, 403 means rejected or canceled.
`claims`List of Claim	The claims requested

Errors:

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

Example:

$ SUBJECT="vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co"
$ curl -u ":$API_KEY" \
  "https://nametag.co/people/$SUBJECT/properties/govtid_expired,name"
{
  "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
  "properties": [
    {
      "expires": 1637321520,
      "claim": "govtid_expired",
      "value": "false",
      "status": 200
    },
    {
      "expires": 1637321520,
      "claim": "name",
      "value": "Ross Kinder",
      "status": 200
    }
  ],
  "requests": [
    {
      "created_at": "2022-12-18T19:15:42.315853Z",
      "id": "f5cb153e-b96a-42c6-a1c0-f5a27d065fea",
      "claims": [
        "govtid_expired",
        "name"
      ],
      "status": 200
    }
  ]
}

Delete properties

A person may revoke your access to a claim 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 from your app.

Method: DELETE

URL: https://nametag.co/people/*SUBJECT*/properties/*CLAIMS*

Authentication: API key.

Parameters:

SUBJECT - The subject you got back from the /token endpoint which uniquely identifies the person.
CLAIMS - A comma-separated list of the claims 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/govtid_expired,name"

Get properties in bulk

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

Note: You should use 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:

BulkRequest struct
`requests`List of BulkRequestItem	A list of property requests, one for each person about whom you are requesting information.

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

BulkRequestItem struct
`subject`string	The subject of the request. This is the person whose properties are being requested.
`claims`List of Claim	Which claims you are requesting for this person.

Response:

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

BulkResponse struct
`data`List of PropertiesResponse	A list of responses for each person requested.

Example:

$ curl -u ":$API_KEY" https://nametag.co/people/bulk \
  -d '{
  "requests": [
    {
      "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
      "claims": [
        "govtid_expired",
        "name"
      ]
    }
  ]
}'
{
  "data": [
    {
      "subject": "vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",
      "properties": [
        {
          "expires": 1637321520,
          "claim": "govtid_expired",
          "value": "true",
          "status": 200
        },
        {
          "expires": 1637321520,
          "claim": "name",
          "value": "Alice Smith",
          "status": 200
        }
      ]
    }
  ]
}

Compare values

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

Use this endpoint 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 claim is name.

Method: POST

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

Authentication: API key

Request body:

SubjectComparisonRequest struct
`expectations`List of Expectation	A list of expectations to compare against the person's properties.

Expectation struct
`claim`Claim	The claim you are comparing against.
`value`string	The value you expect the person to have for this claim.

Response:

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

ComparisonResult struct
`confidence`floating-point number	A number between 0 and 1 that represents Nametag's confidence that the value matches the expected value. A value of 1 means Nametag is very confident that the values match, while 0 means that the values do not match at all.
`comparisons`List of Comparison	A list of comparisons between the expected and actual values.

Comparison struct
`claim`Claim	The claim being compared.
`expected`string	The expected value for this claim.
`actual`string	The actual value for this claim.
`match`boolean	True if the `match_confidence` exceeds Nametag's recommended threshold for a match, false otherwise.
`match_confidence`floating-point number	A number between 0 and 1 that represents Nametag's confidence that the values match. A value of 1 means Nametag is very confident that the values match, while 0 means that the values do not match at all.

Example:

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

{
  "confidence": 0.9,
  "comparisons": [
    {
      "claim": "name",
      "expected": "Alice Smith",
      "value": "Alice Catherine Smith",
      "match_confidence": 0.96,
      "match": true
    }
  ]
}

Compare selfie

Use this endpoint if your want to tell if a photo of a user matches the photo on their government ID.

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

For the best results, you must upload a photo that:

has exactly one face in it.
is neither extremely dark not extremely bright.
does not exceed 5 MB.
is at least 100x100 pixels.
is no more than 10,000 x 10,000 pixels.
the face occupies an area of least 100x100 pixels

Note: Although the picture claim is required, this endpoint does not compare the uploaded photo against the profile picture. Instead, it compares the actual selfie 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)

Request parameters:

extra_validation (optional)

Specifies additional validation to perform on the input image.

If the employee_badge validation is specified, the input image is checked to ensure that it is appropriate for use as a professional badge photo. This includes checks that the image is well-lit, that the face is clearly visible, and that there are no obstructions such as sunglasses or hats.

Response:

CompareSelfieResult struct
`match`boolean	True if the `match_confidence` exceeds Nametag's recommended threshold for a match, false otherwise.
`confidence`floating-point number	A number between 0 and 1 that represents Nametag's confidence that the values match. A value of 1 means Nametag is very confident that the values match, while 0 means that the values do not match at all.
`no_face`boolean (optional)	The photo provided does not contain a person's face.
`not_matched`boolean (optional)	The face in the photo provided does not match any of the selfies on file for this person.
`multiple_faces`boolean (optional)	The photo provided contains more than one face.
`employee_badge`EmployeeBadgeValidationResult (optional)

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 Nametag 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 *SHARED_SECRET* as the key. The shared secret can be found in the Nametag console.

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

Example: Verifying the signature on the command line.

WEBHOOK_SHARED_SECRET="webhook-683fb6598c7faa4f05e4e693d3686f5faa6b9cd7bb646c5254edd3cb880f4225"
X_NAMETAG_SIGNATURE="e51e995e66aabc85f5f15f3c9dcdf859757aa117fd7ab13ccb61c54057d744f3"
ACTUAL_SIGNATURE=$(echo -n '{"event_type":"share",'\
    '"subject":"vkljipkaio2ap663do54r5fp2a@5lsqfg1luqzb9s.nametag.co",'\
	'"request":"f9cbc40a-5da2-4f1c-84a6-f8e097fca03c",'\
    '"claims":["name"]}' |\
  openssl dgst -sha256 -hmac "$WEBHOOK_SHARED_SECRET" |\
  awk '{print $2}')
if [ "$ACTUAL_SIGNATURE" = "$X_NAMETAG_SIGNATURE" ]; then
  echo "Signature matched, process request"
else
  echo "Signature did not match, reject request"
fi

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

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

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:

WebhookPayloadShare struct
`event_type`string	Always `"share"` for this event type
`subject`string	The subject that shared the data
`request`string (optional)	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.
`org_name`string (optional)	The currently configured name of the organization in which the environment is configured
`env_name`string (optional)	The currently configured name of the environment that generated the webhook
`claims`List of Claim	The list of currently shared claims
`label`string	The label assigned to the request

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",
  "claims": [
    "name"
  ]
}

Revoke event

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

Event type: revoke

Request body:

WebhookPayloadReject struct
`event_type`string	Always `"reject"` for this event type
`subject`string	The Subject that initially shared the data
`request`string (optional)	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.
`org_name`string (optional)	The currently configured name of the organization in which the environment is configured
`env_name`string (optional)	The currently configured name of the environment that generated the webhook
`claims`List of Claim	The list of revoked claims
`label`string	The label assigned to the request

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

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

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

Recover event

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

Event type: recover

Request body:

WebhookPayloadRecover struct
`event_type`string	Always `"recover"` for this event type
`subject`string	The Nametag identifier of the person who recovered an account
`language`string	The language preferences of the user, as reported by their browser's `Accept-Language` header
`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.
`action`RecoveryKind	The type of recovery that occurred, either `password-reset`, `mfa-reset`, or `unlock`.
`org_name`string	The currently configured name of the organization in which the environment is configured
`env_name`string	The currently configured name of the environment that generated the webhook
`date`RFC 3339 date-time string	The time when the recovery completed.

RecoveryKind enum
`password-reset`
`mfa-reset`
`unlock`
`account-binding`
`temporary-access-pass`

Response body: (optional)

WebhookResponseRecover struct
`deny_user_message`string (optional)	If specified, then the recovery operation is not allowed and the user is presented with the specified message. Use `language` to determine the language of the end user and translate appropriately, if necessary. The format of the message is markdown.

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

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

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

Rejecting a recovery operation

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

To reject the recovery operation your webhook handler must:

Respond with an HTTP status code of 200

Any status code other than 200 will result in the recovery being prevented and a message starting with the phrase A custom integration failed will be presented to the end-user.
Set the Content-type response header to application/json

The response body must contain a valid JSON document like:

{
  "deny_user_message": "This message is displayed to the end-user"
}

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

Request event

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

Event type: request

Request body:

WebhookPayloadRequest struct
`event_type`string	Always `"request"` for this event type
`event`RequestEventType	The reason this event was emitted. This field is provided for transparency about why the webhook is being emitted. The possible values of may change over time and are not part of the API contract. We recommend that you use the status information in the `request.progress` and `request.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 the `scan_*` events are not emitted. The `request.status` field is your best source of truth.
`request`Request	Information about the request

The event_type field will have one of the following values:

RequestEventType enum
`request_created`	A new request has been initiated and recorded in the system.
`request_accepted`	The request was completed.
`request_rejected`	The request was rejected because the evidence presented was insufficient or invalid.
`request_canceled`	The request has been canceled by the user or system before completion.
`request_app_opened`	The user opened the Nametag app.
`request_email_selected`	The user selected which email address they will share.
`request_link_opened`	The request link was opened in the browser.
`request_selfie_verified`	The user's selfie has been successfully verified against their ID and the selfie chain.
`request_label_changed`	The request label was updated.
`request_data_deletion_status_changed`	The customer requested the end user data not to be deleted due to suspicion of fraud.
`request_oauth_code_issued`	An OAuth authorization code has been issued as part of the request.
`request_oauth_token_issued`	An OAuth access token has been issued following successful authentication.
`request_expired`	The request has exceeded the allowed time limit and is no longer valid.
`scan_started`	The user started scanning their ID.
`scan_front_image_added`	The user uploaded an image of the front of their ID.
`scan_back_image_added`	The user uploaded an image of the back of their ID.
`scan_selfie_image_added`	The user uploaded an image of their selfie.
`scan_selfie_smile_added`	The user uploaded an image of their second selfie (in PAD mode only)
`scan_aadhaar_added`	Aadhaar details have been added to the scan request.
`scan_aadhaar_otp_added`	Aadhaar OTP details have been added to the scan request.
`scan_finished`	The user finished scanning their ID.
`scan_aborted`	The user canceled the ID scan before they finished.
`scan_appealed`	Nametag rejected the user's ID and the user has appealed.
`scan_appeal_accepted`	A Nametag reviewer has reviewed the user's appeal and accepted it.
`scan_appeal_rejected`	A Nametag reviewer has reviewed the user's appeal and rejected it.
`scan_accepted`	The user's scanned ID is valid.
`scan_rejected`	The user's scanned ID is invalid.
`biometric_consent`	The end user has provided consent for biometric data collection.
`end_user_revoke`	The end user has revoked consent or authorization for the request.
`vendor_revoke`	You (the requestor) have revoked authorization for the request.
`vault_phone_added`	A phone number has been added to the user's vault.
`vault_phone_verified`	The added phone number has been successfully verified.
`vault_phone_resent`	A verification request for the phone number has been resent.
`vault_phone_deleted`	The phone number has been removed from the user's vault.
`vault_email_added`	An email address has been added to the user's vault.
`vault_email_verified`	The added email address has been successfully verified.
`vault_email_resent`	A verification request for the email address has been resent.
`vault_email_deleted`	The email address has been removed from the user's vault.
`vault_profile_picture_added`	A profile picture has been added to the user's vault.
`vault_profile_picture_removed`	The profile picture has been removed from the user's vault.
`vault_preferred_name_set`	The user's preferred name has been set in the vault.
`profile_picture_accepted`	The profile picture has been reviewed and accepted.
`profile_picture_rejected`	The profile picture has been reviewed and rejected.
`vault_deleted`	The user's vault and all associated data have been deleted.
`scan_passport_nfc_added`	The user uploaded the data stored on the NFC chip from their passport.

Directory provider error event

This event is emitted whenever an error occurs in the directory provider.

Event type: directory_provider_err

Request body:

WebhookPayloadDirectoryProviderErr struct
`event_type`string	Always `"directory_provider_err"` for this event type
`language`string	The language preferences of the user, as reported by their browser's `Accept-Language` header
`directory`string	The ID of the directory service that was used to recover the account
`directory_kind`DirectoryKind	The type of directory.
`action`DirectoryProviderAction	The action that raise the error
`org_name`string	The currently configured name of the organization in which the environment is configured
`env_name`string	The currently configured name of the environment that generated the webhook
`date`RFC 3339 date-time string	The time when the recovery completed.
`subject`string (optional)	The Nametag identifier of the person. This field is present only for actions that are related to a specific account.
`external_id`string (optional)	The ID of the user in the directory. This field is present only for actions that are related to a specific account.
`context`WebhookPayloadDirectoryProviderErrContext (optional)	Provides tracing information to help correlate this event with other logs or system activity
`error`string	Contains error details when the action fails

The action field will have one of the following values:

DirectoryProviderAction enum
`sync`	The sync action is triggered when directory sync fails
`user_reset_password`	The user_reset_password action is triggered when a user attempts to reset their password
`user_reset_mfa`	The user_reset_mfa action is triggered when a user attempts to reset their MFA
`user_unlock`	The user_unlock action is triggered when a user attempts to unlock their account
`user_temporary_access_pass`	The user_temporary_access_pass action is triggered when a user attempts to get temporary access pass
`user_create_bypass_code`	The user_create_bypass_code action is triggered when a user attempts to create bypass code

The context field is an object with the following fields:

WebhookPayloadDirectoryProviderErrContext struct
`provider_request_id`string (optional)	A unique identifier that links this event to a specific transaction. Useful for log tracing and debugging.

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: cd2cf39f-fa65-4847-955c-d10603224794
X-Nametag-Signature: b2e23938a8b00f738f72cab035f73082639a63f571ca96b1a7cda48e82ecbb4f

{
  "event_type": "directory_provider_err",
  "language": "",
  "directory": "f40350cc-c2b4-4ced-85ec-c05f081df963",
  "directory_kind": "custom",
  "action": "sync",
  "org_name": "My Company",
  "env_name": "Live",
  "date": "2025-07-21T18:21:13.917067Z",
  "subject": "",
  "external_id": "",
  "context": {
    "provider_request_id": ""
  },
  "error": "agent: failed to list users: directory agent is not connected"
}

Picture event

This event is emitted when a user adds or updates a photo using the /badge portion of the self-service site.

Event type: picture

Request body:

WebhookPayloadPicture struct
`event_type`string	Always `"picture"` for this event type
`kind`string	The type of picture that was submitted. Currently, the only supported value is `"badge"`, which indicates a verified batch photo.
`subject`string	The Nametag identifier of the person that submitted the picture
`request`string	The Nametag request ID of the verification
`name`string	The verified name of the person that submitted the picture
`url`URL string	A URL where the picture can be downloaded. The URL is valid for 15 minutes.
`sha256`string	A SHA256 hash of the picture
`error`string (optional)	If the picture was rejected, this field contains a description of why the picture was rejected.

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: cd2cf39f-fa65-4847-955c-d10603224794
X-Nametag-Signature: b2e23938a8b00f738f72cab035f73082639a63f571ca96b1a7cda48e82ecbb4f

{
  "event_type": "picture",
  "kind": "badge",
  "subject": "pibdix2u",
  "request": "r5p75264",
  "name": "Alice Smith",
  "url": "https://nametagusercontent.com/res/ZqqyvsUKcNI0SQl_-VcKVQpris2G5WOomPhYot4g6_UsoM5-E2PYmGiMrdk5lw65eRN7zzlejIPqgFLg9G8schN-v9L2YJqse23Bjv__98-rU3SKVrmKdYJ9N5Nh9FW-F7USL4OZQyBl4o0RXJK0seZy_jAd6cqzJbGRfNsVliuEtwNlvlxNaE3KPICgablfgU-BRg",
  "sha256": "2jKzxhpgwRORIk9E8iI+jHvo5090g3qvKz4w+4mcxjw=",
  "error": "Background is plain black; company rules require a neutral white/gray/blue background for badge photos."
}

Accounts API

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

List accounts

Method: GET

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

Authentication: API key

Query parameters:

Parameter	Description
`env`	Optional List only accounts in the specified environment. Can be specified multiple times, in which case accounts from each specified environment are returned.
`count`	Optional Limit the query to the specified number of accounts. (Default: 50)
`offset`	Optional Return the page of results starting with the specified offset, returned in the `next_offset` field of the response.
`directory`	Optional List only accounts in the specified directory. Can be specified multiple times, in which case accounts from each specified directory are returned.

Response:

AccountsList struct
`accounts`List of Account	The list of accounts
`next_offset`integer (optional)	A value for the offset query parameter for the next page of results

Each item in accounts is an object consisting of:

Account struct
`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 a 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 (optional)	The Nametag Subject for this person, if the account has been bound to a `subject`. Null otherwise.
`have_birth_date`boolean (optional)	true if the person's expected birth date has been set for the directory.
`photo`AccountPhoto (optional)	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:

AccountPhoto struct
`sha256`string	The SHA256 hash of the uploaded image.
`created_at`RFC 3339 date-time string	The time when the image was added.

Get an account

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

Method: GET

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

Authentication: API key

Response: Account

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

Update an account

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

Method: PATCH

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

Authentication: API key

Request:

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

AccountUpdateRequest struct
`birth_date`string (optional)	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. You can also specify the hash or HMAC of the person's birth date. See Birth date hashes for details.
`subject`string (optional)	The subject for this person. Set this to an empty string to remove the binding for this person.

Response: none

Add a photo

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

Method: PUT

URL: https://nametag.co/api/accounts/*ACCOUNT_ID*/photo

Authentication: API key

Request: JPEG, PNG, WebP, TIFF, GIF, SVG, or AVIF 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 image, or does not contain exactly one legible face.

Note: Photos must not be larger than 7 MB

Example:

$ curl -X PUT "https://nametag.co/api/accounts/300901511-fab5-4f1e-11b4-00fa44e11111/photo" \
  --header 'Content-Type: image/jpeg' \
  --header 'Authorization: Bearer *API_KEY*' \
  --data-binary '@/mypath/my-photo.jpeg'

Remove a photo

Removes a photo from an account. The ACCOUNT_ID can be either the id, one of the directory_identifiers or directory_immutable_identifier for the account.

Method: DELETE

URL: https://nametag.co/api/accounts/*ACCOUNT_ID*/photo

Authentication: API key

Example:

$ curl -X DELETE "https://nametag.co/api/accounts/300901511-fab5-4f1e-11b4-00fa44e11111/photo" \
  --header 'Authorization: Bearer *API_KEY*' \

Bulk update accounts

Method: PATCH

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

Authentication: API key

Request:

AccountBulkUpdateRequest struct
`accounts`List of AccountBulkUpdateRequestItem	A list of account update operations

An AccountBulkUpdateRequestItem is an object with the following fields:

AccountBulkUpdateRequestItem struct
`birth_date`string (optional)	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. You can also specify the hash or HMAC of the person's birth date. See Birth date hashes for details.
`id`string	The unique identifier of the account. This can be the Nametag ID for the account, the immutable ID of the account (e.g. the GUID in Azure AD), or one of the identifiers associated with the account, (e.g. the email address, username, or UPN).
`subject`string (optional)	The subject for this person. Set this to an empty string to remove the binding for this person.

Response:

AccountBulkUpdateResponse struct
`results`List of AccountBulkUpdateResponseItem

An AccountBulkUpdateResponseItem is an object with the following fields:

AccountBulkUpdateResponseItem struct
`status`AccountBulkUpdateStatus
`id`string	The account identifier provided in the request
`error`string (optional)	A description of the error that occurred.

A AccountBulkUpdateStatus is one of the following values:

AccountBulkUpdateStatus enum
`204`	The account was updated
`400`	One of the fields to be updated is malformed, e.g. the subject is not valid or not for the environment of the account.
`404`	An account matching the specified ID could not be found
`409`	Multiple accounts with the specified identifier were found

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 500 MB. Split your bulk imports into parts and call this API repeatedly if you need to upload more than 500 MB worth of images.

Response:

BulkUploadAccountPhotosResponse struct
`files`List of BulkUploadAccountPhotosResponseItem	A list of responses, each corresponding to a file in the uploaded archive.

BulkUploadAccountPhotosResponseItem struct
`filename`string	The name of the file
`account_id`string (optional)	The Nametag identifier for the account that matched this file. If this field is absent, then the file was not matched to an existing account.
`directory_identifiers`List of string (optional)	The identifiers for the account used by the directory (typically an email address, username)
`directory_immutable_identifier`string (optional)	The unchanging identifier for the account used by the directory. Most directories have a UUID or other opaque identifier that doesn't change even when `directory_identifiers` changes.
`status`integer	This field is 200 if adding the photo was successful, 404 if an account could not be found, 400 if the image is invalid, or 422 if the image contains multiple faces, doesn't match the existing selfie, or no face at all.
`error`string (optional)	A human-readable error message describing the reason a file could not be processed.

Example:

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

$ zip -r bulk.zip bulk

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

Configuration API

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

Organization

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

Get

Get the organization.

Method: GET

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

Authentication: API key

Response:

Org struct
`name`string	The name of the organization, typically the name of your company
`role`Role	Your role in the organization.
`envs`List of string	A list of the environment IDs that you have access to.

Example:

$ curl -u :$APIKEY "https://nametag.co/api/org"
{
  "name": "Acme Corp",
  "role": "admin",
  "envs": [
    "cfln7ldhawwlen",
    "nwixcd2qkbth7h"
  ]
}

List members

Returns a list of the members of your organization

Method: GET

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

Authentication: API key

Request: none

Response:

ListOrgMembersResponse struct
`members`List of OrgMember	A list of each member of the organization

Each *ORG_MEMBER* is an object consisting of:

OrgMember struct
`member_id`string	A unique identifier of the member.
`role`Role	The person's role in the organization. One of `limited`, `limited_plus`, `user`, `admin`, or `owner`.
`envs`List of string	The list of environments the member has access to. If the list contains `*`, the member has access to all environments.
`name`string	The name of the member.
`email`string	The email address of the member.
`profile_picture`URL string	The URL of the profile picture of the member.
`invite_pending`boolean	True if the member has been invited to the organization but has not yet signed in.
`requests_count`integer (optional)	The number of requests the member has sent.
`principal`string	The principal of this org member

The Role enumeration has one of the following values:

Role enum
`limited`	A limited user can make requests and see responses to their request, but they cannot see responses to other people's requests.
`limited_plus`	Like `limited` but can see request details
`user`	A normal member of the organization. Can manage requests but not environments or members.
`admin`	An administrator of the organization. Admins can invite new members, update member roles, and remove members.
`owner`	The owner of the organization. The owner has full control over the organization, including the ability to delete it.

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:

InviteOrgMemberRequest struct
`email`RFC 822 email address string	The email address of the person you want to invite.
`envs`List of string	The list of environments the member will have access to. If the list contains `*`, the member will have access to all environments.
`role`Role	The role to be assigned to the new member.

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:

UpdateOrgMemberRequest struct
`envs`List of string (optional)	The list of environments the member will have access to. If the list contains `*`, the member will have access to all environments.
`role`Role (optional)	The role to be assigned to the member.

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

Response: none

Environment

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

Env struct
`id`string	The identifier for this environment
`name`string	The internal name for this environment
`public_name`string	The name of the environment that is shared with people
`logo_url`URL string	A URL to your logo, which is displayed in the Nametag mobile app.
`terms_of_service_url`URL string	The URL of the terms of service. Formerly, this URL was provided to end-users in the Nametag mobile app, but it is no longer used.
`callback_urls`List of URL string	A list of valid URLs for use as OAuth 2.0 callback URLs.
`webhooks`List of WebhookDefinition	A list of webhooks.
`templates`List of Template	A list of request templates.
`storage`EnvStorage (optional)
`oidc_delegates`List of OIDCDelegate	A list of OIDC Delegates.

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

WebhookDefinition struct
`id`string	A unique identifier for the webhook definition.
`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 WebhookEventType	The names of the events that should be sent.
`authorization_header`string (optional)	The value of the Authorization header to include in the webhook request.

WebhookEventType enum
`share`	Send Share events to this webhook
`reject`	Send Reject events to this webhook
`recover`	Send Recover events to this webhook
`request`	Send Request events to this webhook
`audit`	Send Audit events to this webhook
`directory_provider_err`	Send Directory Provider Err events to this webhook
`picture`	Send Picture events to this webhook

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

EnvStorage struct
`s3_bucket_us`string (optional)	The S3 bucket for data stored in the United States. Must be in the us-east-2 AWS region.
`s3_bucket_eu`string (optional)	The S3 bucket for data stored in Europe. Must be in the eu-west-1 AWS region.
`s3_bucket_in`string (optional)	The S3 bucket for data stored in India. Must be in the ap-south-1 AWS region.
`aws_role_arn`string (optional)	The role Nametag should use to access the S3 buckets.
`azure_blob_us`string (optional)	Azure Blob Storage presigned (SAS) URL. Should be in the eastus region.
`azure_blob_eu`string (optional)	Azure Blob Storage presigned (SAS) URL. Should be in the northeurope region.
`azure_blob_in`string (optional)	Azure Blob Storage presigned (SAS) URL. Should be in the centralindia region.

`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:

Template struct
`id`string	A unique identifier for the template
`created_at`RFC 3339 date-time string	When the template was created
`name`string	A descriptive name of the template
`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.
`is_default`boolean	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`integer	How long the data sharing authorization should last, in seconds.
`claim_definitions`List of TemplateClaimDefinition	A list of claims that are requested when requests are created with this template.
`claims_expire_in`integer	How long the data sharing authorization should last, in seconds.
`enabled`boolean	If true, then this template is enabled for requests. The default template must be enabled.
`require_selfie_reverification`boolean	If true, existing users must provide a new selfie to validate their identity.
`qr_custom_text`string	The text that appears below the desktop QR page headline.

`TemplateScopeDefinition`

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

TemplateScopeDefinition struct
`scope`Scope	The name of the scope that is requested

`TemplateClaimDefinition`

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

TemplateClaimDefinition struct
`claim`Claim	The name of the claim that is requested

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:

ListEnvsResponse struct
`envs`List of Env	A list of all your environments.

Example:

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

Create

Creates a new environment

Method: POST

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

Authentication: API key

Request: empty

Response:

CreateEnvResponse struct
`id`string	The unique identifier of the environment

Example:

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

Get

Fetch the settings for an environment.

Method: GET

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

Authentication: API key

Response: an Env object

Example:

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

Update

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

Method: PATCH

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

Authentication: API key

Request:

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

EnvUpdateRequest struct
`name`string (optional)	Update the name of the environment, for internal use.
`public_name`string (optional)	Update the public-facing name for your environment, typically your company or brand name.
`callback_urls`List of URL string (optional)	Set the list of allowed OAuth 2.0 callback URLs
`terms_of_service_url`string (optional)	Update the terms of service URL.
`remove_webhooks`List of string (optional)	Remove webhooks from the environment (IDs of the webhooks to remove)
`add_webhooks`List of WebhookDefinition (optional)	Add webhooks to the environment
`update_webhook`WebhookDefinitionUpdate (optional)
`storage`EnvStorage (optional)
`remove_oidc_delegates`List of string (optional)	Remove OIDC delegate from the environment (IDs of the delegates to remove)
`add_oidc_delegates`List of OIDCDelegate (optional)	Add OIDC delegates to the environment
`update_oidc_delegate`OIDCDelegateUpdate (optional)

WebhookDefinitionUpdate struct
`id`string
`url`string (optional)
`enabled`boolean (optional)
`events`List of WebhookEventType (optional)
`authorization_header`string (optional)	The value of the Authorization header to include in the webhook request.

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

Example:

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

Update the logo

Method: POST

URL: https://nametag.co/api/envs/*ENV_ID*/logo

Authentication: API key

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

Response: none

Example:

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

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

Remove

Remove an environment.

Method: DELETE

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

Request: none

Response: none

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

Templates

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

Note: there is no API 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:

CreateTemplateRequest struct
`name`string	A descriptive name of the template
`headline`string (optional)	The text that appears at the top of the mobile app when showing the request
`qr_headline`string (optional)	The text that appears above the QR code when directing the user from desktop to mobile.
`expiration_text`string (optional)	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 (optional)	The text on the accept button in the mobile app.
`accepted_text`string (optional)	The text that appears on the confirmation view after a request has been accepted.
`install_message_sms`string (optional)	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.
`is_default`boolean (optional)	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 (optional)	A list of scopes that are requested when requests are created with this template.
`scopes_expire_in`integer (optional)	How long the data sharing authorization should last, in seconds.
`claim_definitions`List of TemplateClaimDefinition (optional)	A list of claims that are requested when requests are created with this template.
`claims_expire_in`integer (optional)	How long the data sharing authorization should last, in seconds.
`enabled`boolean (optional)	If true, then this template is enabled for requests. The default template must be enabled.
`require_selfie_reverification`boolean (optional)	If true, existing users must provide a new selfie to validate their identity.
`qr_custom_text`string (optional)	The text that appears below the desktop QR page headline.

Response:

CreateTemplateResponse struct
`id`string	The unique identifier of the template

Example:

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

Modify a template

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

Method: PATCH

URL: https://nametag.co/api/envs/*ENV_ID*/templates/*TEMPLATE_ID*

Request:

UpdateTemplateRequest struct
`name`string (optional)	A descriptive name of the template
`headline`string (optional)	The text that appears at the top of the mobile app when showing the request
`qr_headline`string (optional)	The text that appears above the QR code when directing the user from desktop to mobile.
`expiration_text`string (optional)	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 (optional)	The text on the accept button in the mobile app.
`accepted_text`string (optional)	The text that appears on the confirmation view after a request has been accepted.
`install_message_sms`string (optional)	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.
`is_default`boolean (optional)	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 (optional)	A list of scopes that are requested when requests are created with this template.
`scopes_expire_in`integer (optional)	How long the data sharing authorization should last, in seconds.
`claim_definitions`List of TemplateClaimDefinition (optional)	A list of scopes that are requested when requests are created with this template.
`claims_expire_in`integer (optional)	How long the data sharing authorization should last, in seconds.
`enabled`boolean (optional)	If true, then this template is enabled for requests. The default template must be enabled.
`require_selfie_reverification`boolean (optional)	If true, existing users must provide a new selfie to validate their identity.
`qr_custom_text`string (optional)	The text that appears below the desktop QR page headline.

Response: none

Example:

Update the headline for a template:

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

Delete a template

Removes a template.

Method: DELETE

URL: https://nametag.co/api/envs/*ENV_ID*/templates/*TEMPLATE_ID*

Request: none

Response: none

Example:

Update the headline for a template:

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

Directories

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

Create

Create a directory.

Method: POST

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

Request:

CreateDirectoryRequest struct

envstring

The ID of the environment to create this directory for

kindDirectoryKind

The type of directory to create

credentialsCredentials (optional)

Credentials to access the directory.

Provide credentials for directories that require it
("okta", "duo", "onelogin", "beyond-identity"). Omit for "azure-ad".

DirectoryKind enum
`azure-ad`	An Entra ID (formerly Azure Active Directory) directory
`okta`	An Okta directory
`duo`	A Duo Security directory
`onelogin`	A OneLogin directory
`custom`	A custom directory
`beyond-identity`	A Beyond Identity directory

Credentials struct
`account`string (optional)	For Duo, the integration key For Okta, this field should be blank For Onelogin, the client ID, e.g. `98ea6e4f216f2fb4b69fff9b3a44842c38686ca685f3f55dc48c5d3fb1107be4` For BeyondIdentity, the client ID, e.g. `Tf9IGY976IqEjEHJrYSJW7JF`
`application_id`string (optional)	For Duo, this field should be blank For Okta, this field should be blank For Onelogin, this field should be blank For BeyondIdentity, the application ID, e.g. `9f6b7c1e-2d44-4c2b-8c9f-3ab59e92c123`
`partition`string	For Duo, the API hostname, e.g. `api-33091yc9.duosecurity.com`. For Okta, the service hostname, e.g. `your-company.okta.com`. For Onelogin, the subdomain, e.g. `example.onelogin.com`. For BeyondIdentity, the BaseURL, e.g. `https://api-us.beyondidentity.com`.
`realm_id`string (optional)	For Duo, this field should be blank For Okta, this field should be blank For Onelogin, this field should be blank For BeyondIdentity, the realm ID, e.g. `8b4e3oxk01qwu19`
`secret`string	For Duo, the secret key, e.g. `cv9wJSC10XDFRGY5L9DcgHuNtR76vM8kuB1sDCpc` For Okta, the API token, e.g. `21lgux-M8uJC4w-9kN_PL0ivV5tM81AvSd7l0IuAS3` For Onelogin, the client secret, e.g. `f3d4bd80d4d4007be3455453819d3359f8a5eb2eb66fdbc7bae5e44083605118` For BeyondIdentity, the client secret, e.g. `Y0p8Q~a1Bx3K-4lHnV9zYt2sA7jRkLmF5gS9xTqW`
`tenant_id`string (optional)	For Duo, this field should be blank For Okta, this field should be blank For Onelogin, this field should be blank For BeyondIdentity, the tenant ID, e.g. `1124mn2az1yglqq`

Response:

CreateDirectoryResponse struct

agent_tokenstring (optional)

idstring

The unique identifier for the directory.

redirect_urlstring (optional)

The OAuth 2.0 redirect URL to authorize the directory.

If the directory uses OAuth 2.0 for authorization (e.g. "azure-ad"), then
this field contains the URL to redirect the user to authorize the directory.

List

Fetches information about each directory

Method: GET

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

Response:

The count field is the number of entries in the directory, as of the most recent synchronization.

GetDirectoriesResponse struct
`directories`List of Directory	A list of all directories.

Directory struct
`recovery_operation_rate_limit`RecoveryOperationRateLimit (optional)
`can_get_mfa_bypass_code`boolean (optional)	true if the directory supports generating an MFA bypass code
`can_get_password_link`boolean (optional)	true if the directory supports issuing a pre-authenticated password reset link
`can_get_temporary_access_pass`boolean (optional)	true if the directory supports issuing a temporary access pass
`can_get_temporary_password`boolean (optional)	true if the directory supports issuing a temporary password
`can_remove_all_mfa`boolean (optional)	true if the directory supports removing all MFA devices
`can_unlock`boolean (optional)	true if the directory supports unlocking a locked account
`can_update_accounts_list`boolean (optional)	true if the directory supports progressive updates to the list of accounts
`logo_url`URL string (optional)	The URL of the logo image for this directory.
`id`string	The unique identifier for the directory.
`env`string	The environment this directory belongs to.
`kind`DirectoryKind	The kind of directory this is
`name`string	The internal name of the directory. This field is derived from inspecting the directory itself, for example for Entra ID this field is the primary domain name. This field is used to help you identify the directory.
`authenticate_policy`RecoveryPolicyRules	The policy governing using Nametag as an authentication factor
`mfa_policy`RecoveryPolicyRules	The policy governing MFA reset
`password_policy`RecoveryPolicyRules	The policy governing password reset
`unlock_policy`RecoveryPolicyRules	The policy governing account unlock
`temporary_access_pass_policy`RecoveryPolicyRules	The policy governing generating a temporary access pass.
`temporary_access_pass_lifetime_minutes`integer (optional)	The validity period of a temporary access pass in minutes. For Entra ID, this value must be between 10 and 43200 (equivalent to 30 days). If not specified, the defaultLifetimeInMinutes setting in the Temporary Access Pass authentication method policy is applied.
`temporary_access_pass_reusable`boolean (optional)	True if temporary access passes can be used more than once. If unspecified, temporary access passes are usable only once.
`credentials`PartialCredentials (optional)	The directory credentials used, not including any secret values.
`last_sync_started_at`RFC 3339 date-time string (optional)	When the last sync started.
`last_sync_completed_at`RFC 3339 date-time string (optional)	When the last sync completed
`last_sync_error`string (optional)	An error describing the failure of the last sync, or null if the last sync was successful.
`count`integer (optional)	The number of accounts in the directory.
`needs_reconnect`boolean (optional)	If the directory needs to reconnect.
`sync_running`boolean	true if the directory sync is currently running
`birth_date_hmac_secret_exists`boolean	true if a shared secret for birth date HMACs has been set
`directory_secret`base64 encoded binary data (string) (optional)	the directory secret used by external clients for integration scenarios

PartialCredentials struct
`account`string	For Duo, the integration key For Okta, this field should be blank For Onelogin, the client ID, e.g. `98ea6e4f216f2fb4b69fff9b3a44842c38686ca685f3f55dc48c5d3fb1107be4`
`partition`string	For Duo, the API hostname, e.g. `api-33091yc9.duosecurity.com`. For Okta, the service hostname, e.g. `your-company.okta.com`. For Onelogin, the subdomain, e.g. `example.onelogin.com`.

RecoveryPolicyRules struct
`groups`List of GroupRecoveryPolicy	A list of policies to apply based on an Account's group membership. When Nametag evaluates policy, the first entry in this list that matches will be applied. If no group matches, then the default policy is applied.
`default`RecoveryPolicy	The default policy when the account is not a member of any of the groups in the `groups` field.

GroupRecoveryPolicy struct
`group`DirectoryGroup	The group to which this policy applies.
`policy`RecoveryPolicy	The policy to apply when the account is a member of the group.

DirectoryGroup struct
`directory_immutable_identifier`string	The unique identifier for the group.
`name`string	The display name of the group.

RecoveryPolicy enum
`weak_name_match`	The operation can proceed if the name on the account matches the person's legal name. Rejection for highly-common names is disabled. If the Account is augmented with a birth date then the birth date must match. If the account is augmented with a photo, then only the photo must match.
`name_match`	The operation can proceed if the name on the account matches the person's legal name. If the Account is augmented with a birth date, then the birth date must match. If the account is augmented with a photo, then only the photo must match.
`name_and_birth_date`	The operation can proceed if both the name and birth date match between the Account and the person's ID. If the account is augmented with a photo, then only the photo must match.
`photo`	The operation can only proceed if the account is augmented with a photo and the photo matches the person's ID.
`disabled`	The operation is disabled.

Delete

Deletes a directory

Method: DELETE

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

Request: none

Response: none

Synchronize

Trigger synchronization of the directory.

Note: Synchronization happens automatically once per hour.

Method: POST

URL: https://nametag.co/api/directories/*DIRECTORY_ID*/sync

Request: none

Response: none

Authorize

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

Method: GET

URL: https://nametag.co/api/directories/*DIRECTORY_ID*/authorize

Request: none

Response:

OAuth2AuthorizeResponse struct
`redirect_url`string	The URL to redirect the user to authorize the directory.

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:

ListAPIKeysResponse struct
`apikeys`List of APIKey	A list of API keys

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

APIKey struct
`id`string	The unique identifier for the API key
`name`string	A descriptive name for the API key
`created_at`RFC 3339 date-time string	When the API key was created
`created_by`string (optional)	The OrgMember ID that created this API key.
`enabled`boolean	Whether the API key is enabled.
`envs`List of string	The unique identifier for the environments this API key belongs to, or `["*"]` if the key applies to all environments.
`role`Role	The role assigned to the API key. The role determines what actions the API key can perform.
`expires_at`RFC 3339 date-time string (optional)	The expiration date and time for the API key. If not provided, the key will not expire. Example: "2023-12-31T23:59:59Z"
`last_used_at`RFC 3339 date-time string (optional)	The last time the API key was used. This is updated each time the key is used to make a request.

Example:

$ curl -u :$APIKEY https://nametag.co/api/apikeys
{
  "apikeys": [
    {
      "id": "06c6a11a-c78e-488f-9b58-f73362309ea0",
      "envs": ["*"],
      "name": "Staging API Key",
      "created_at": "2022-03-15T22:39:59Z",
      "role": "admin",
      "enabled": true
    }
  ]
}

Create

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

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

Method: POST

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

Authentication: API key

Request:

CreateAPIKeyRequest struct
`name`string (optional)	A descriptive name for the API key
`enabled`boolean (optional)	`true` if the API key is enabled, or `false` if it cannot be used.
`envs`List of string	The unique identifier for the environments this API key belongs to, or `["*"]` if the key applies to all environments.
`role`Role (optional)	The role to be associated with the API key. The role determines what actions the API key can perform.
`expires_at`RFC 3339 date-time string (optional)	The expiration date and time for the API key. If not provided, the key will not expire. Example: "2023-12-31T23:59:59Z"

Response:

CreateAPIKeyResponse struct
`id`string	The unique identifier for the API key
`key`string	The full secret API key

Example: Creating a global API key

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

Example: Creating an environment-scoped API key

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

Get

Fetch information about an API key

Method: GET

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

Authentication: API key

Request: none

Response: an APIKey object

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

Audit API

The audit API allows you to fetch logs of actions taken by users in the Nametag console or using the API.

List

Fetches a list of audit logs.

Method: GET

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

Authentication: API key with the Owner role

Query parameters:

Parameter	Format	Description
`start`	RFC 3339 full-date	Optional The start of the time range to fetch logs for. Defaults to 24 hours ago.
`count`	integer	Optional The maximum number of logs to fetch. Defaults to 512.

Response:

ListAuditEventsResponse struct
`backward_cursor`string (optional)
`forward_cursor`string (optional)
`events`List of AuditEvent	A list of audit events

Each item in events is an object consisting of:

AuditEvent struct
`id`string	The unique identifier for the event. The identifier is in ULID format which means that you can sort the events by time by sorting by ID.
`time`RFC 3339 date-time string	The time the event occurred
`kind`AuditEventKind	Which type of event this is.
`truncated`boolean (optional)	True if the details of this record have been removed because the record would exceed the size limit for audit logs.
`trace`string	A unique identifier for the event
`remote_addr`string (optional)	The IP address of the client that made the request
`user_agent`string (optional)	The remote user agent of the client that made the request
`org`string	The ID of the organization for the actor performing the action. This will be the same for all your events.
`env`string (optional)	The ID of the environment that this action refers to.
`principal`Principal (optional)	The principal associated with the event
`env_created`EnvCreatedAuditEvent (optional)
`env_updated`EnvUpdatedAuditEvent (optional)
`env_deleted`EnvDeletedAuditEvent (optional)
`env_logo_uploaded`EnvLogoUploadedAuditEvent (optional)
`env_logo_deleted`EnvLogoDeletedAuditEvent (optional)
`template_created`TemplateCreatedAuditEvent (optional)
`template_updated`TemplateUpdatedAuditEvent (optional)
`template_deleted`TemplateDeletedAuditEvent (optional)
`env_webhook_secret_updated`EnvWebhookSecretUpdatedAuditEvent (optional)
`org_updated`OrgUpdatedAuditEvent (optional)
`org_member_invited`OrgMemberInvitedAuditEvent (optional)
`org_member_removed`OrgMemberRemovedAuditEvent (optional)
`org_member_updated`OrgMemberUpdatedAuditEvent (optional)
`apikey_created`APIKeyCreatedAuditEvent (optional)
`apikey_updated`APIKeyUpdatedAuditEvent (optional)
`apikey_deleted`APIKeyDeletedAuditEvent (optional)
`request_created`RequestCreatedAuditEvent (optional)
`request_updated`RequestUpdatedAuditEvent (optional)
`request_canceled`RequestCanceledAuditEvent (optional)
`account_updated`AccountUpdatedAuditEvent (optional)
`account_photo_uploaded`AccountPhotoUploadedAuditEvent (optional)
`directory_created`DirectoryCreatedAuditEvent (optional)
`directory_updated`DirectoryUpdatedAuditEvent (optional)
`directory_deleted`DirectoryDeletedAuditEvent (optional)
`directory_authorized`DirectoryAuthorizedAuditEvent (optional)
`directory_set_credentials`DirectorySetCredentialsAuditEvent (optional)
`directory_logo_uploaded`DirectoryLogoUploadedAuditEvent (optional)
`directory_logo_deleted`DirectoryLogoDeletedAuditEvent (optional)
`console_signin`ConsoleSigninAuditEvent (optional)
`console_singin_configure_email`ConsoleSinginConfigureEmailAuditEvent (optional)
`console_singin_configure_saml`ConsoleSinginConfigureSAMLAuditEvent (optional)
`cli_signin`CLISigninAuditEvent (optional)
`oauth2_pushed_authorization_request`OAuth2PushedAuthorizationRequestAuditEvent (optional)
`oauth2_authorize`OAuth2AuthorizeAuditEvent (optional)
`oauth2_v2_authorize`OAuth2V2AuthorizeAuditEvent (optional)
`oauth2_request_canceled`OAuth2RequestCanceledAuditEvent (optional)
`oauth2_token`OAuth2TokenAuditEvent (optional)
`entra_eam_authorize`EntraEamAuthorizeAuditEvent (optional)
`entra_eam_finish`EntraEamFinishAuditEvent (optional)
`okta_eam_authorize`OktaEamAuthorizeAuditEvent (optional)
`okta_eam_finish`OktaEamFinishAuditEvent (optional)
`people_compare`PeopleCompareAuditEvent (optional)
`selfie_compare`SelfieCompareAuditEvent (optional)
`sharing_revoked`SharingRevokedAuditEvent (optional)
`extension_invoked`ExtensionInvokedAuditEvent (optional)

The principal field describes the authenticated user who performed the action. It contains the following fields:

Principal struct
`role`Role	The role associated with the OrgMember or API key
`org_member`string (optional)	The ID of the OrgMember for the console user performing the action
`org_member_email`string (optional)	The email address associated with the OrgMember
`api_key`string (optional)	The ID of the APIKey for the actor performing the action.
`impersonator`string (optional)	Present if the request was made by a Nametag administrator on behalf of the user. The value is the email address of the Nametag administrator performing the action.
`subject`string (optional)	If the request was authenticated using an ID token, then this is the subject of the ID token.

Exactly one of the following fields will be set:

EnvCreatedAuditEvent struct
`request`CreateEnvRequest
`response`CreateEnvResponse

CreateEnvRequest struct

EnvUpdatedAuditEvent struct
`request`EnvUpdateRequest

EnvDeletedAuditEvent struct
`empty`boolean (optional)

EnvLogoUploadedAuditEvent struct
`kind`string

EnvLogoDeletedAuditEvent struct
`kind`string

TemplateCreatedAuditEvent struct
`request`CreateTemplateRequest
`response`CreateTemplateResponse

TemplateUpdatedAuditEvent struct
`request`UpdateTemplateRequest
`template`string

TemplateDeletedAuditEvent struct
`template`string

EnvWebhookSecretUpdatedAuditEvent struct
`empty`boolean (optional)

OrgUpdatedAuditEvent struct
`request`OrgUpdateRequest

OrgUpdateRequest struct
`name`string (optional)	The name of the organization, typically the name of your company
`allowed_ip_addresses`List of string (optional)

OrgMemberInvitedAuditEvent struct
`request`InviteOrgMemberRequest

OrgMemberRemovedAuditEvent struct
`org_member`string

OrgMemberUpdatedAuditEvent struct
`org_member`string
`request`UpdateOrgMemberRequest

APIKeyCreatedAuditEvent struct
`request`CreateAPIKeyRequest
`response`CreateAPIKeyResponse

APIKeyUpdatedAuditEvent struct
`apikey`string
`request`APIKeyUpdateRequest

APIKeyUpdateRequest struct
`name`string (optional)	A descriptive name for the API key
`enabled`boolean (optional)	`true` if the API key is enabled, or `false` if it cannot be used.
`role`Role (optional)	The role assigned to the API key. The role determines what actions the API key can perform.
`envs`List of string (optional)	The unique identifier for the environments this API key belongs to, or `["*"]` if the key applies to all environments.
`expires_at`RFC 3339 date-time string (optional)	The expiration date and time for the API key. If not provided, the key will not expire. Example: "2023-12-31T23:59:59Z"

APIKeyDeletedAuditEvent struct
`apikey`string

RequestCreatedAuditEvent struct
`request`CreateRequestRequest
`response`CreateRequestResponse

RequestUpdatedAuditEvent struct
`request_id`string
`request`UpdateRequestRequest

RequestCanceledAuditEvent struct
`request_id`string

AccountUpdatedAuditEvent struct
`account`string
`directory`string
`request`AccountUpdateRequest

AccountPhotoUploadedAuditEvent struct
`account`string
`directory`string

DirectoryCreatedAuditEvent struct
`request`CreateDirectoryRequest
`response`CreateDirectoryResponse

DirectoryUpdatedAuditEvent struct
`directory`string
`request`UpdateDirectoryRequest

DirectoryLogoUploadedAuditEvent struct
`directory`string

DirectoryLogoDeletedAuditEvent struct
`directory`string

UpdateDirectoryRequest struct
`authenticate_policy`RecoveryPolicyRules (optional)
`password_policy`RecoveryPolicyRules (optional)
`mfa_policy`RecoveryPolicyRules (optional)
`unlock_policy`RecoveryPolicyRules (optional)
`temporary_access_pass_policy`RecoveryPolicyRules (optional)
`temporary_access_pass_lifetime_minutes`integer (optional)	The validity period of a temporary access pass in minutes
`temporary_access_pass_reusable`boolean (optional)	True if temporary access passes can be used more than once
`birth_date_hmac_secret`base64 encoded binary data (string) (optional)	A shared secret for hashed birth dates in the directory
`recovery_operation_rate_limit`RecoveryOperationRateLimit (optional)

DirectoryDeletedAuditEvent struct
`directory`string

DirectoryAuthorizedAuditEvent struct
`directory`string

DirectorySetCredentialsAuditEvent struct
`directory`string

ConsoleSigninAuditEvent struct
`email`boolean (optional)	True if the user authenticated via email
`nametag`boolean (optional)	True if the user authenticated via Nametag (deprecated)
`relay_state`string (optional)	If the user authenticated via SAML, the RelayState parameter
`saml`boolean (optional)	True if the user authenticated via SAML
`saml_response`string (optional)	If the user authenticated via SAML, the RelayState parameter

ConsoleSinginConfigureEmailAuditEvent struct
`empty`boolean (optional)

ConsoleSinginConfigureSAMLAuditEvent struct
`empty`boolean (optional)

CLISigninAuditEvent struct
`session`string

OAuth2AuthorizeAuditEvent struct
`request`AuthorizeRequest
`response`AuthorizeResponse

OAuth2AuthorizeAuditEvent struct
`request`AuthorizeRequest
`response`AuthorizeResponse

AuthorizeRequest struct
`claim`List of Claim (optional)	Space-separated list of claims
`client_id`string	The client ID
`code_challenge`string (optional)	The code challenge
`code_challenge_method`string (optional)	The code challenge method
`email_hint`RFC 822 email address string (optional)	The email hint
`redirect_uri`string	The redirect URI
`response_mode`string (optional)	The response mode
`response_type`string (optional)	The response type
`return`AuthorizeReturn (optional)
`scope`List of Scope (optional)	Space-separated list of scopes
`state`string	The state
`template`string (optional)	The template to use

AuthorizeReturn enum

`chrome`
`firefox`
`https`

AuthorizeResponse struct
`error_message`string (optional)
`redirect_uri`string (optional)
`env_name`string (optional)
`qrcode`base64 encoded binary data (string) (optional)
`install_ticket`string (optional)
`request`string (optional)
`session_token`string (optional)
`app_clip_experience`string (optional)
`return`AuthorizeReturn

OAuth2TokenAuditEvent struct
`request`TokenRequest
`response`TokenResponse

TokenRequest struct
`grant_type`string
`client_id`string
`client_secret`string
`redirect_uri`string
`code`string
`code_verifier`string (optional)

TokenResponse struct
`access_token`string
`refresh_token`string
`id_token`string
`scope`string
`claims`string
`expires_in`integer
`token_type`string
`subject`string

OAuth2RequestCanceledAuditEvent struct
`request`string

EntraEamAuthorizeAuditEvent struct
`directory`string
`request`EntraEamAuthorizeRequest
`response`EntraEamAuthorizeResponse

EntraEamAuthorizeRequest struct
`claims`string
`client_id`string
`client_request_id`string
`id_token_hint`string
`nonce`string
`redirect_uri`string
`response_mode`string
`response_type`string
`scope`string
`state`string

EntraEamAuthorizeResponse struct
`oauth2_client_id`string
`oauth2_redirect_uri`string
`oauth2_server`string
`oauth2_template`string
`state`string

EntraEamFinishAuditEvent struct
`directory`string
`request`EntraEamFinishRequest
`response`EntraEamFinishResponse

EntraEamFinishRequest struct
`code`string (optional)
`error`string (optional)
`state`string

EntraEamFinishResponse struct
`binding_failed`boolean (optional)
`error`string (optional)
`id_token`string (optional)
`oauth2_state`string (optional)
`redirect_uri`string (optional)

OktaEamAuthorizeAuditEvent struct
`directory`string
`request`OktaEamAuthorizeRequest
`response`OktaEamAuthorizeResponse

OktaEamAuthorizeRequest struct
`claims`string
`client_id`string
`login_hint`string
`redirect_uri`string
`response_type`string
`scope`string
`state`string

OktaEamAuthorizeResponse struct
`oauth2_client_id`string
`oauth2_redirect_uri`string
`oauth2_server`string
`oauth2_template`string
`state`string

OktaEamFinishAuditEvent struct
`directory`string
`request`OktaEamFinishRequest
`response`OktaEamFinishResponse

OktaEamFinishRequest struct
`code`string (optional)
`error`string (optional)
`state`string

OktaEamFinishResponse struct
`binding_failed`boolean (optional)
`code`string (optional)
`error`string (optional)
`id_token`string (optional)
`oauth2_state`string (optional)
`redirect_uri`string (optional)
`request_timeout`boolean (optional)

PeopleCompareAuditEvent struct
`request`SubjectComparisonRequest
`response`ComparisonResult

SelfieCompareAuditEvent struct
`response`CompareSelfieResult
`subject`string

SharingRevokedAuditEvent struct
`claims`List of Claim
`subject`string

API Reference

Overview

Claims

The Email claim

The Account claim

Scopes

Subject

Environments

Organizations

Basics

Authentication

Response codes

Rate limits

Request API

Create authorization

Request authorization

Completing authorization

Token endpoint

Create a request

Get a request

RequestStatus

RequestProgress

RequestProperties

GovtidValue

GovtidType

RequestMobileDevice

Location

RequestBrowser

RequestDetails

Update a request

Cancel a request

People API

Get properties

Delete properties

Get properties in bulk

Compare values

Compare selfie

Webhooks

Share event

Revoke event

Recover event

Rejecting a recovery operation

Request event

Directory provider error event

Picture event

Accounts API

List accounts

Get an account

Update an account

Add a photo

Remove a photo

Bulk update accounts

Bulk photo upload

Configuration API

Organization

Get

List members

Invite a person to your organization

Remove an organization member

Set a member’s role

Environment

Template

TemplateScopeDefinition

TemplateClaimDefinition

List environments

Create

Get

Update

Update the logo

Remove

Templates

Create a template

Modify a template

Delete a template

Directories

Create

List

Delete

Synchronize

Authorize

The `Email` claim

The `Account` claim

`RequestStatus`

`RequestProgress`

`RequestProperties`

`GovtidValue`

`GovtidType`

`RequestMobileDevice`

`Location`

`RequestBrowser`

`RequestDetails`

`Template`

`TemplateScopeDefinition`

`TemplateClaimDefinition`