NTP

Methods for creating and managing NTP instances and tickets

CreateNTPInstance

CreateNTPInstance({
  tenantId,
  objectId,
  groupAddresses, // optional
  ntpClass, // optional
  maxTickets, // optional
  maxRedemptions, // optional
  startTime,
  endTime,
  ticketLength // optional
}) → Promise.<string>

Issue an n-time-password (NTP) instance. This instance contains a specification for the tickets (AKA codes) to be issued, including the target(s) to be authorized, how many tickets can be issued, and when and how many times tickets can be redeemed.

Note: For date types (startTime/endTime), you may specify the date in any format parsable by JavaScript's new Date() constructor, including Unix epoch timestamps and ISO strings

Returns: The ID of the NTP instance. This ID can be used when issuing tickets (See IssueNTPCode)

Parameters

Name	Type	Required	Description
tenantId	string	✓	The ID of the tenant in which to create the NTP instance
objectId	string	✓	ID of the object for the tickets to be authorized to
groupAddresses	Array.<string>		List of group addresses for the tickets to inherit permissions from
ntpClass	number		Class of NTP instance to create (default: 4)
maxTickets	number		The maximum number of tickets that may be issued for this instance (if 0, no limit) (default: 0)
maxRedemptions	number		The maximum number of times each ticket may be redeemed (default: 100)
startTime	string | number	✓	The time when issued tickets can be redeemed
endTime	string | number	✓	The time when issued tickets can no longer be redeemed
ticketLength	number		The number of characters in each ticket code (default: 6)

DeleteNTPInstance

DeleteNTPInstance({
  tenantId,
  ntpId
})

Delete the specified NTP instance. This action cannot be undone.

Parameters

Name	Type	Required	Description
tenantId	string	✓	The ID of the tenant in which this NTP instance was created
ntpId	string	✓	The ID of the NTP instance

IssueNTPCode

IssueNTPCode({
  tenantId,
  ntpId,
  email, // optional
  maxRedemptions // optional
}) → Promise.<Object>

Issue a ticket from the specified NTP ID

Returns: The generated ticket code and additional information about the ticket.

Parameters

Name	Type	Required	Description
tenantId	string	✓	The ID of the tenant in the NTP instance was created
ntpId	string	✓	The ID of the NTP instance from which to issue a ticket
email	string		The email address associated with this ticket. If specified, the email address will have to be provided along with the ticket code in order to redeem the ticket.
maxRedemptions	number		Maximum number of times this ticket may be redeemed. If less than the max redemptions of the NTP instance, the lower limit will be used.

IssueSignedNTPCode

IssueSignedNTPCode({
  tenantId,
  ntpId,
  email, // optional
  maxRedemptions // optional
}) → Promise.<Object>

Identical to IssueNTPCode, but the token is also signed by the current user.

Returns: The generated signed ticket code and additional information about the ticket.

Parameters

Name	Type	Required	Description
tenantId	string	✓	The ID of the tenant in the NTP instance was created
ntpId	string	✓	The ID of the NTP instance from which to issue a ticket
email	string		The email address associated with this ticket. If specified, the email address will have to be provided along with the ticket code in order to redeem the ticket.
maxRedemptions	number		Maximum number of times this ticket may be redeemed. If less than the max redemptions of the NTP instance, the lower limit will be used.

ListNTPInstances

ListNTPInstances({
  tenantId,
  count, // optional
  offset // optional
}) → Object

Retrieve info for NTP instances in the specified tenant

Returns: List of NTP instances along with pagination information

Parameters

Name	Type	Required	Description
tenantId	string	✓	The ID of the tenant
count	number		Maximum number of results to return (default: 10)
offset	number		Offset from which to return results (default: 0)

NTPInstance

NTPInstance({
  tenantId,
  ntpId
}) → Object

Retrieve a info about the specified NTP instance

Returns: Info about the NTP instance

Parameters

Name	Type	Required	Description
tenantId	string	✓	The ID of the tenant
ntpId	string	✓	The ID of the NTP instance

RedeemCode

RedeemCode({
  issuer, // optional
  tenantId, // optional
  ntpId, // optional
  code,
  email, // optional
  includeNTPId // optional
}) → Promise.<(string|Object)>

Redeem the specified ticket/code to authorize the client. Must provide either issuer or tenantId and ntpId

Returns: The object ID which the ticket is authorized to, or an object containing the object ID and NTP ID if includeNTPId is specified

Parameters

Name	Type	Required	Description
issuer	string		Issuer to authorize against
tenantId	string		The ID of the tenant from which the ticket was issued
ntpId	string		The ID of the NTP instance from which the ticket was issued
code	string	✓	Access code
email	string		Email address associated with the code
includeNTPId	boolean		If specified, the response will include both the target object ID as well as the NTP ID associated with the ticket

SuspendNTPInstance

SuspendNTPInstance({
  tenantId,
  ntpId
})

Suspend the specified NTP instance. All tickets issued for this instance will be considered expired.

To reactivate the NTP instance, reset the expiration date using UpdateNTPInstance

Parameters

Name	Type	Required	Description
tenantId	string	✓	The ID of the tenant in which this NTP instance was created
ntpId	string	✓	The ID of the NTP instance

UpdateNTPInstance

UpdateNTPInstance({
  tenantId,
  ntpId,
  maxTickets, // optional
  maxRedemptions, // optional
  startTime,
  endTime
}) → Object

Update the attributes of the specified NTP instance. Only the specified attributes will be updated ; others will be unchanged.

Returns: Info about the NTP Instance

Parameters

Name	Type	Required	Description
tenantId	string	✓	The ID of the tenant in which this NTP instance was created
ntpId	string	✓	The ID of the NTP instance to update
maxTickets	number		The maximum number of tickets that may be issued for this instance (if 0, no limit) (default: 0)
maxRedemptions	number		The maximum number of times each ticket may be redeemed (default: 100)
startTime	string | number	✓	The time when issued tickets can be redeemed
endTime	string | number	✓	The time when issued tickets can no longer be redeemed