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: |
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}
Parametersid
: 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}
Parametersid
: 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: |
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: |
message | string | Human readable value providing more detail about the error. |