notificationcenter (1.0)

Download OpenAPI specification:Download

The (OX Protect) Notification Center takes care of sending messages to users. This can be real-time security alerts as well as other security related or informal messages, based on events generated by various source like PowerDNS, Anti Abuse Shield or other sources.

Authentication

X-API-Key

Security scheme type: API Key
header parameter name: X-API-Key

user

The user API to manage the users of the notifcationcenter

Create a user

post /user
/notificationcenter/api/v1/user
Authorizations:
Request Body schema: application/json
emailaddress
Array of object (EmailAddress)
locale
string

The selected language of the user

phonenumbers
Array of object (PhoneNumber)
pushtokens
Array of object (PushToken)
userMappings
Array of object (UserMapping)
user_id
required
string [ 1 .. 50 ] characters

Unique user id for notification centre

Responses

200

OK

201

Successful created. The return value is the id of the created user.

400

Invalid input data

401

Unauthorized

403

Forbidden

404

Not Found

409

User already exists

500

Unexpected error

Request samples

application/json
Copy
Expand all Collapse all
{
  • "emailaddress":
    [
    ],
  • "locale": "string",
  • "phonenumbers":
    [
    ],
  • "pushtokens":
    [
    ],
  • "userMappings":
    [
    ],
  • "user_id": "string"
}

Delete a user

delete /user/{userId}
/notificationcenter/api/v1/user/{userId}
Authorizations:
path Parameters
userId
required
string

The id of the user to delete

Responses

200

OK

204

Successful deleted

401

Unauthorized

403

Forbidden

404

User does not exists

500

Unexpected error

Get a user with the userId

get /user/{userId}
/notificationcenter/api/v1/user/{userId}
Authorizations:
path Parameters
userId
required
string

The user id of the user to get

Responses

200

Successful

401

Unauthorized

403

Forbidden

404

User does not exists

500

Unexpected error

Response samples

application/json
Copy
Expand all Collapse all
{
  • "emailaddress":
    [
    ],
  • "id": 0,
  • "locale": "string",
  • "phonenumbers":
    [
    ],
  • "pushtokens":
    [
    ],
  • "userMappings":
    [
    ],
  • "user_id": "string"
}

Partial update of a user

patch /user/{userId}
/notificationcenter/api/v1/user/{userId}
Authorizations:
path Parameters
userId
required
string

The current id of the user to update

Request Body schema: application/json
locale
string

The selected language of the user

user_id
string

Unique user id for notification centre

Responses

200

Successful updated

204

No Content

400

Invalid input data

401

Unauthorized

403

Forbidden

404

User does not exists

500

Unexpected error

Request samples

application/json
Copy
Expand all Collapse all
{
  • "locale": "string",
  • "user_id": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "emailaddress":
    [
    ],
  • "id": 0,
  • "locale": "string",
  • "phonenumbers":
    [
    ],
  • "pushtokens":
    [
    ],
  • "userMappings":
    [
    ],
  • "user_id": "string"
}

Update or create a user

put /user/{userId}
/notificationcenter/api/v1/user/{userId}
Authorizations:
path Parameters
userId
required
string

The current id of the user to update

query Parameters
create
boolean

Create if not exists?

add
boolean

Add and not replace notification channels?

Request Body schema: application/json
emailaddress
Array of object (EmailAddress)
locale
string

The selected language of the user

phonenumbers
Array of object (PhoneNumber)
pushtokens
Array of object (PushToken)
userMappings
Array of object (UserMapping)
user_id
required
string [ 1 .. 50 ] characters

Unique user id for notification centre

Responses

200

Successful updated

201

Created

400

Invalid input data

401

Unauthorized

403

Forbidden

404

User does not exists

500

Unexpected error

Request samples

application/json
Copy
Expand all Collapse all
{
  • "emailaddress":
    [
    ],
  • "locale": "string",
  • "phonenumbers":
    [
    ],
  • "pushtokens":
    [
    ],
  • "userMappings":
    [
    ],
  • "user_id": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 0,
  • "message": "string"
}

Get the current channel configuration of all channels of the user with the userId. If there is no channel configuration the lists of the configuration will be empty

get /user/{userId}/channelconfiguration
/notificationcenter/api/v1/user/{userId}/channelconfiguration
Authorizations:
path Parameters
userId
required
string

Id of the user to create the device for

Responses

200

Successful operation

401

Unauthorized

403

Forbidden

404

User not found

500

Unexpected error

Response samples

application/json
Copy
Expand all Collapse all
{
  • "email":
    {
    },
  • "push":
    {
    },
  • "sms":
    {
    }
}

Sets or updates the channel configuration of all channels of the user with the userId. The old channel configurations will be overwritten completly

put /user/{userId}/channelconfiguration
/notificationcenter/api/v1/user/{userId}/channelconfiguration
Authorizations:
path Parameters
userId
required
string

Id of the user to create the notificationconfiguration for

Request Body schema: application/json
email
object (ChannelConfiguration)

The configuration for a channel to send notifications to a user. The object contains a whitelist. Each notification which has a category or code which is mentioned in configuration list will be send. If the list is empty all notifications will be send.

push
object (ChannelConfiguration)

The configuration for a channel to send notifications to a user. The object contains a whitelist. Each notification which has a category or code which is mentioned in configuration list will be send. If the list is empty all notifications will be send.

sms
object (ChannelConfiguration)

The configuration for a channel to send notifications to a user. The object contains a whitelist. Each notification which has a category or code which is mentioned in configuration list will be send. If the list is empty all notifications will be send.

Responses

200

Successful operation

201

Created

401

Unauthorized

403

Forbidden

404

User not found

500

Unexpected error

Request samples

application/json
Copy
Expand all Collapse all
{
  • "email":
    {
    },
  • "push":
    {
    },
  • "sms":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "email":
    {
    },
  • "push":
    {
    },
  • "sms":
    {
    }
}

users

The users API to get the users list and count of the notifcationcenter

Get a complete list of all registered users

get /users
/notificationcenter/api/v1/users
Authorizations:
query Parameters
page
integer <int32>

page index of paging

size
integer <int32>

size of a page in paging

Responses

200

successful operation

401

Unauthorized

403

Forbidden

404

Not Found

500

Unexpected error

Response samples

application/json
Copy
Expand all Collapse all
{
  • "elements":
    [
    ],
  • "pageCurrent": 0,
  • "pageSize": 0,
  • "pagesTotal": 0,
  • "size": 0
}

Add a list of new users to the notificationcenter. If there is already a user of the list registered at the notificationcenter none of the users will be added and an error will be returned.

post /users
/notificationcenter/api/v1/users
Authorizations:
Request Body schema: application/json
Array
emailaddress
Array of object (EmailAddress)
locale
string

The selected language of the user

phonenumbers
Array of object (PhoneNumber)
pushtokens
Array of object (PushToken)
userMappings
Array of object (UserMapping)
user_id
required
string [ 1 .. 50 ] characters

Unique user id for notification centre

Responses

200

OK

201

successful operation

400

Invalid data for example an user exists already in the notificationcenter

401

Unauthorized

403

Forbidden

404

Not Found

500

Unexpected error

Request samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Add a list of new users to the notificationcenter. If there is already a user of the list registered at the notificationcenter the user will be updated.

put /users
/notificationcenter/api/v1/users
Authorizations:
Request Body schema: application/json
Array
emailaddress
Array of object (EmailAddress)
locale
string

The selected language of the user

phonenumbers
Array of object (PhoneNumber)
pushtokens
Array of object (PushToken)
userMappings
Array of object (UserMapping)
user_id
required
string [ 1 .. 50 ] characters

Unique user id for notification centre

Responses

200

successful operation

201

Created

400

Invalid data

401

Unauthorized

403

Forbidden

404

Not Found

500

Unexpected error

Request samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get count of all registered users

get /users/count
/notificationcenter/api/v1/users/count
Authorizations:

Responses

200

successful operation

401

Unauthorized

403

Forbidden

404

Not Found

500

Unexpected error

Response samples

application/json
Copy
Expand all Collapse all
0

notifications

The notification api for getting a notication or many notifications by id

Create a notification

post /notification
/notificationcenter/api/v1/notification
Authorizations:
Request Body schema: application/json
app
required
string

The identifier of the application that generated the notification.

broadcast
boolean

Whether the notification has been broadcasted to all users.

categories
Array of string

The names of all classification categories that caused to block a request.

code
required
string
Enum:"NOTIFY_INFO" "PROTECT_NOTIFY_BLOCKED_MALWARE" "PROTECT_NOTIFY_BLOCKED_FILTER_CATEGORY" "PROTECT_NOTIFY_BLOCKED_FILTER_BLACKLIST" "PROTECT_NOTIFY_NEW_DEVICE" "NOTIFY_LOGIN_SUCC" "NOTIFY_LOGIN_FAILED" "NOTIFY_LOGIN_SUSPICIOUS"

Integral notification type identifier.

NOTIFY_INFO| Just an informal notification that should be displayed to the user, e.g. an outage announcement.
PROTECT_NOTIFY_BLOCKED_MALWARE| Request was blocked because of malware.
PROTECT_NOTIFY_BLOCKED_FILTER_CATEGORY| Request was blocked because of a filter rule, category.
PROTECT_NOTIFY_BLOCKED_FILTER_BLACKLIST| Request was blocked because of a filter rule, blacklist.
PROTECT_NOTIFY_NEW_DEVICE| A new device was detected.
NOTIFY_LOGIN_SUCC| Just an informal notification that the user has been logged in successfully.
NOTIFY_LOGIN_FAILED| Just an informal notification that the user failed to login.
NOTIFY_LOGIN_SUSPICIOUS| The user has logged in from somewhere but the login is suspicious.

device_id
string [ 0 .. 50 ] characters

The identifier of the affected (e.g. blocked) device. Empty string if the notification does not belong to a specific device.

device_ip
string

The IP address of the affected (e.g. blocked) device. Empty string if the notification does not belong to a specific device.

device_name
string

The name of the new device. The value of this property will only be recognized when the code is PROTECT_NOTIFY_NEW_DEVICE.

device_type
string

The type of the new device. The value of this property will only be recognized when the code is PROTECT_NOTIFY_NEW_DEVICE.

excluded_push_token
object (NotificationTokenRepresentation)
hidden
boolean

Indicator if the notification is hidden.

severity
string
Enum:"LOW" "MEDIUM" "HIGH"

An identifier for the severity of the notification.

text
string

An arbitrary explicit notification text to be shown to the user.

timestamp
required
string <date-time>

ISO-8601 time stamp of the notification, e.g. '2017-07-11T11:09:54'

url
string

The URL that was blocked by a filter rule.

user_id
required
string [ 1 .. 50 ] characters

The identifier of the user owning the notification.

Responses

200

OK

201

Successful created

400

Invalid input data for example timestamp of notification is in the future

401

Unauthorized

403

Forbidden

404

Not Found

409

Notification already exists

500

Unexpected error

Request samples

application/json
Copy
Expand all Collapse all
{
  • "app": "string",
  • "broadcast": true,
  • "categories":
    [
    ],
  • "code": "NOTIFY_INFO",
  • "device_id": "string",
  • "device_ip": "string",
  • "device_name": "string",
  • "device_type": "string",
  • "excluded_push_token":
    {
    },
  • "hidden": true,
  • "severity": "LOW",
  • "text": "string",
  • "timestamp": "2019-08-17T11:39:04Z",
  • "url": "string",
  • "user_id": "string"
}

Update a notification

patch /user/{userId}/notification/{notificationId}
/notificationcenter/api/v1/user/{userId}/notification/{notificationId}
Authorizations:
path Parameters
userId
required
string

Id of the user to update the notifications for

notificationId
required
string

Id of the the notifications to update

Request Body schema: application/json
hidden
boolean

Indicator if the notification is hidden.

Responses

200

Successful updated

204

No Content

401

Unauthorized

403

Forbidden

404

Notification with id not found

500

Unexpected error

Request samples

application/json
Copy
Expand all Collapse all
{
  • "hidden": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "app": "string",
  • "broadcast": true,
  • "categories":
    [
    ],
  • "code": "NOTIFY_INFO",
  • "device_id": "string",
  • "device_ip": "string",
  • "device_name": "string",
  • "device_type": "string",
  • "excluded_push_token":
    {
    },
  • "hidden": true,
  • "id": "string",
  • "severity": "LOW",
  • "text": "string",
  • "timestamp": "2019-08-17T11:39:04Z",
  • "url": "string",
  • "user_id": "string"
}

Get notifications assigned to user with userId

get /user/{userId}/notifications
/notificationcenter/api/v1/user/{userId}/notifications
Authorizations:
path Parameters
userId
required
string

Id of the user to get the notifications for

query Parameters
page
integer <int32>

page index of paging

size
integer <int32>

size of a page in paging

sort
required
string
Enum:"ASC" "DESC"

Sort by timestamp. Possible values are ASC(ascending) or DESC(descending)

Responses

200

Successful operation

401

Unauthorized

403

Forbidden

404

Not Found

500

Unexpected error

Response samples

application/json
Copy
Expand all Collapse all
{
  • "elements":
    [
    ],
  • "pageCurrent": 0,
  • "pageSize": 0,
  • "pagesTotal": 0,
  • "size": 0
}

Get notifications assigned to user with userId filtered by the information of the body ordered by creation date

post /user/{userId}/notifications
/notificationcenter/api/v1/user/{userId}/notifications
Authorizations:
path Parameters
userId
required
string

Id of the user to get the notifications for

query Parameters
page
integer <int32>

page index of paging

size
integer <int32>

size of a page in paging

whitelistfilter
boolean

Use filter as a whitelistfilter?

sort
required
string
Enum:"ASC" "DESC"

Sort by timestamp. Possible values are ASC(ascending) or DESC(descending)

Request Body schema: application/json
categories
Array of string

list of categories to search for

codes
Array of string
Items Enum:"NOTIFY_INFO" "PROTECT_NOTIFY_BLOCKED_MALWARE" "PROTECT_NOTIFY_BLOCKED_FILTER_CATEGORY" "PROTECT_NOTIFY_BLOCKED_FILTER_BLACKLIST" "PROTECT_NOTIFY_NEW_DEVICE" "NOTIFY_LOGIN_SUCC" "NOTIFY_LOGIN_FAILED" "NOTIFY_LOGIN_SUSPICIOUS"

list of types to search for

deviceIds
Array of string

list of deviceIds to search for

deviceIps
Array of string

list of deviceIps to search for

remember_youngest_not_timestamp
boolean

Remember the timestamp of the youngest notification

show_hidden
boolean

Indicator if hidden notifications should be selected.

sites
Array of string

list of sites to search for

time
object (TimePeriod)

from until search

Responses

200

Successful operation

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

500

Unexpected error

Request samples

application/json
Copy
Expand all Collapse all
{
  • "categories":
    [
    ],
  • "codes":
    [
    ],
  • "deviceIds":
    [
    ],
  • "deviceIps":
    [
    ],
  • "remember_youngest_not_timestamp": true,
  • "show_hidden": true,
  • "sites":
    [
    ],
  • "time":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "elements":
    [
    ],
  • "pageCurrent": 0,
  • "pageSize": 0,
  • "pagesTotal": 0,
  • "size": 0
}

Get count notifications assigned to user with userId

get /user/{userId}/notifications/count
/notificationcenter/api/v1/user/{userId}/notifications/count
Authorizations:
path Parameters
userId
required
string

Id of the user to get the notifications for

Responses

200

Successful operation

401

Unauthorized

403

Forbidden

404

Not Found

500

Unexpected error

Response samples

application/json
Copy
Expand all Collapse all
0

Get count notifications assigned to user with userId filtered by information of the body

post /user/{userId}/notifications/count
/notificationcenter/api/v1/user/{userId}/notifications/count
Authorizations:
path Parameters
userId
required
string

Id of the user to get the notifications for

query Parameters
whitelistfilter
boolean

Use filter as a whitelistfilter?

Request Body schema: application/json
categories
Array of string

list of categories to search for

codes
Array of string
Items Enum:"NOTIFY_INFO" "PROTECT_NOTIFY_BLOCKED_MALWARE" "PROTECT_NOTIFY_BLOCKED_FILTER_CATEGORY" "PROTECT_NOTIFY_BLOCKED_FILTER_BLACKLIST" "PROTECT_NOTIFY_NEW_DEVICE" "NOTIFY_LOGIN_SUCC" "NOTIFY_LOGIN_FAILED" "NOTIFY_LOGIN_SUSPICIOUS"

list of types to search for

deviceIds
Array of string

list of deviceIds to search for

deviceIps
Array of string

list of deviceIps to search for

remember_youngest_not_timestamp
boolean

Remember the timestamp of the youngest notification

show_hidden
boolean

Indicator if hidden notifications should be selected.

sites
Array of string

list of sites to search for

time
object (TimePeriod)

from until search

Responses

200

Successful operation

201

Created

401

Unauthorized

403

Forbidden

404

Not Found

500

Unexpected error

Request samples

application/json
Copy
Expand all Collapse all
{
  • "categories":
    [
    ],
  • "codes":
    [
    ],
  • "deviceIds":
    [
    ],
  • "deviceIps":
    [
    ],
  • "remember_youngest_not_timestamp": true,
  • "show_hidden": true,
  • "sites":
    [
    ],
  • "time":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
0

Get count of new notifications. The filter for the post notifications endpoint has a parameter called remember_youngest_not_timestamp. If this value is true the timestampof the youngest notification will be remembered. When you call this endpoint the count all notifications that have a younger timestamp than this notification will be returned.

get /user/{userId}/notifications/countnew
/notificationcenter/api/v1/user/{userId}/notifications/countnew
Authorizations:
path Parameters