PushAuth™ API

Use the PushAuth API to initiate PushAuth sessions and check on their status.

PushAuthenticationSession Object

The PushAuthenticationSession object represents a PushAuth attempt, and is the response object returned for all successful Push Authentication API endpoints. In situations where a user has multiple registered devices, a single PushAuthenticationSession can represent multiple push notifications.

Name Type Description
id string The PushAuth session ID.
status string The status of the PushAuth session.

Enum:
sent, accepted, rejected, expired, canceled, error

notificationCount integer The number of clients to which a notification was successfully sent out.
detail string The detail string provided by the SDK when responding to the PushAuth notification.
expiresAt string Timestamp of when the session expires.

Format: date-time
updatedAt string Timestamp of when the session was last updated.

Format: date-time

Create a PushAuth session

This API is used to initiate a PushAuth session.

POST /v1/push/sessions

Request Body

Request body format: application/json.

Name Type Description
user string The id of the user for which the PushAuth session is being initiated. This must match the user supplied in the SDK.
required
notification object These are the properties of the push notification to be presented to the user.

title string

The title of the notification. A default title will be set if this property is not provided.

subtitle string

The subtitle of the notification.

body string

The body of the notification.

payload string

The payload of the notification.
secondsToExpire integer The number of seconds the PushAuth session is valid without user response before expiring. If omitted or 0 is provided, then the default expiration duration will be used. This value also determines the notifications' TTL values. See the APNs and FCM documentation on TTL for more details.

Minimum: 0

Default: 86400

Response

201 UnifyID has successfully initiated a PushAuth session. Returns an instance of PushAuthenticationSession.

Retrieve a PushAuth session

This API call is used to get the status of a PushAuth session. You can use the response as a factor in your decision to let the user through or not.

GET /v1/push/sessions/{id}

Parameters
id: The PushAuth session id

Response

200 This response indicates we were able to successfully look up the status of this PushAuth session. Refer to the status to see if and how the user has responded. Returns an instance of PushAuthenticationSession.

400 A badRequest type error may be returned when there are missing or invalid parameters. Returns an instance of Error.

Update a PushAuth session

This API call is used to update the status of a PushAuth session. Currently, there is only support for canceling a session.

PATCH /v1/push/sessions/{id}

Parameters
id: The PushAuth session id

Request Body

Request body format: application/json.

Name Type Description
status string Tell UnifyID the value with which to update the status of the PushAuth session. Currently only canceling a session is supported.
required

Enum:
canceled

Response

200 This response indicates we were able to successfully update the PushAuth session for the user. Returns an instance of PushAuthenticationSession.

400 A badRequest type error may be returned when there are missing or invalid parameters. Returns an instance of Error.

Errors

Errors returned by the API follow a consistent structure.

Name Type Description
code string A code representing the type of error encountered.

Enum:
invalidRequest, badRequest, unauthorized, forbidden, internalError

message string Human readable value providing more detail about the error.

Updated: