Subscriptions

The Subscriptions API provides operations to manage email subscription settings for Okta administrator notifications.

List all Subscriptions for a Role
OAuth 2.0: okta.roles.read

Lists all subscriptions available to a specified Role

Request
path Parameters
required
RoleType (string) or roleId (string)

A reference to an existing role. Standard roles require a roleType, while Custom Roles require a roleId. See Standard Roles.

Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/roles/{roleRef}/subscriptions
Request samples 
Response samples 
application/json
[
  • {
    • "channels": [
      ],
    • "notificationType": "AD_AGENT",
    • "status": "subscribed",
    • "_links": {
      }
    }
]
Retrieve a Subscription for a Role
OAuth 2.0: okta.roles.read
Retrieves a subscription by notificationType for a specified Role


Request 
path Parameters
required
RoleType (string) or roleId (string)
A reference to an existing role. Standard roles require a roleType, while Custom Roles require a roleId. See Standard Roles.


 
notificationType
required
string (NotificationType) 
The type of notification


 Enum: Description
AD_AGENT
System notification sent when an AD agent disconnects or reconnects


AGENT_AUTO_UPDATE_NOTIFICATION
System notification sent when an agent automatically updates


APP_IMPORT
System notification sent with the status of an app user import


CONNECTOR_AGENT
System notification sent when an on-premises provisioning or Okta on-prem MFA agent disconnects or reconnects


IWA_AGENT
System notification sent when an IGA agent disconnects or reconnects


LDAP_AGENT
System notification sent when an LDAP agent disconnects or reconnects


OKTA_ANNOUNCEMENT
Okta communication sent for announcements and release notes


OKTA_ISSUE
Okta communication sent for trust incident alerts and updates


OKTA_UPDATE
Okta communication sent for scheduled system updates


RATELIMIT_NOTIFICATION
System notification sent when an org reaches rate limit warning or violation thresholds


REPORT_SUSPICIOUS_ACTIVITY
System notification sent when a user reports suspicious activity


USER_DEPROVISION
System notification sent when a user is deprovisioned from apps


USER_LOCKED_OUT
System notification sent when a user is locked out from logging in to Okta


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/roles/{roleRef}/subscriptions/{notificationType}
Request samples 
Response samples 
application/json
{
  • "channels": [
    • "string"
    ],
  • "notificationType": "AD_AGENT",
  • "status": "subscribed",
  • "_links": {
    • "self": {
      }
    }
}
Subscribe a Role to a Specific Notification Type
OAuth 2.0: okta.roles.manage
Subscribes a Role to a specified notification type. Changes to Role subscriptions override the subscription status of any individual users with the Role.


Request 
path Parameters
required
RoleType (string) or roleId (string)
A reference to an existing role. Standard roles require a roleType, while Custom Roles require a roleId. See Standard Roles.


 
notificationType
required
string (NotificationType) 
The type of notification


 Enum: Description
AD_AGENT
System notification sent when an AD agent disconnects or reconnects


AGENT_AUTO_UPDATE_NOTIFICATION
System notification sent when an agent automatically updates


APP_IMPORT
System notification sent with the status of an app user import


CONNECTOR_AGENT
System notification sent when an on-premises provisioning or Okta on-prem MFA agent disconnects or reconnects


IWA_AGENT
System notification sent when an IGA agent disconnects or reconnects


LDAP_AGENT
System notification sent when an LDAP agent disconnects or reconnects


OKTA_ANNOUNCEMENT
Okta communication sent for announcements and release notes


OKTA_ISSUE
Okta communication sent for trust incident alerts and updates


OKTA_UPDATE
Okta communication sent for scheduled system updates


RATELIMIT_NOTIFICATION
System notification sent when an org reaches rate limit warning or violation thresholds


REPORT_SUSPICIOUS_ACTIVITY
System notification sent when a user reports suspicious activity


USER_DEPROVISION
System notification sent when a user is deprovisioned from apps


USER_LOCKED_OUT
System notification sent when a user is locked out from logging in to Okta


 
Responses 
200
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/roles/{roleRef}/subscriptions/{notificationType}/subscribe
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Unsubscribe a Role from a Specific Notification Type
OAuth 2.0: okta.roles.manage
Unsubscribes a Role from a specified notification type. Changes to Role subscriptions override the subscription status of any individual users with the Role.


Request 
path Parameters
required
RoleType (string) or roleId (string)
A reference to an existing role. Standard roles require a roleType, while Custom Roles require a roleId. See Standard Roles.


 
notificationType
required
string (NotificationType) 
The type of notification


 Enum: Description
AD_AGENT
System notification sent when an AD agent disconnects or reconnects


AGENT_AUTO_UPDATE_NOTIFICATION
System notification sent when an agent automatically updates


APP_IMPORT
System notification sent with the status of an app user import


CONNECTOR_AGENT
System notification sent when an on-premises provisioning or Okta on-prem MFA agent disconnects or reconnects


IWA_AGENT
System notification sent when an IGA agent disconnects or reconnects


LDAP_AGENT
System notification sent when an LDAP agent disconnects or reconnects


OKTA_ANNOUNCEMENT
Okta communication sent for announcements and release notes


OKTA_ISSUE
Okta communication sent for trust incident alerts and updates


OKTA_UPDATE
Okta communication sent for scheduled system updates


RATELIMIT_NOTIFICATION
System notification sent when an org reaches rate limit warning or violation thresholds


REPORT_SUSPICIOUS_ACTIVITY
System notification sent when a user reports suspicious activity


USER_DEPROVISION
System notification sent when a user is deprovisioned from apps


USER_LOCKED_OUT
System notification sent when a user is locked out from logging in to Okta


 
Responses 
200
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/roles/{roleRef}/subscriptions/{notificationType}/unsubscribe
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
List all subscriptions for a user
OAuth 2.0: okta.users.read
Lists all subscriptions available to a specified user. Returns an AccessDeniedException message if requests are made for another user.


Request 
path Parameters
userId
required
string
The unique ID of the user


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/subscriptions
Request samples 
Response samples 
application/json
[
  • {
    • "channels": [
      ],
    • "notificationType": "AD_AGENT",
    • "status": "subscribed",
    • "_links": {
      }
    }
]
Retrieve a subscription for a user
OAuth 2.0: okta.users.read
Retrieves a subscription by notificationType for a specified user. Returns an AccessDeniedException message if requests are made for another user.


Request 
path Parameters
userId
required
string
The unique ID of the user


 
notificationType
required
string (NotificationType) 
The type of notification


 Enum: Description
AD_AGENT
System notification sent when an AD agent disconnects or reconnects


AGENT_AUTO_UPDATE_NOTIFICATION
System notification sent when an agent automatically updates


APP_IMPORT
System notification sent with the status of an app user import


CONNECTOR_AGENT
System notification sent when an on-premises provisioning or Okta on-prem MFA agent disconnects or reconnects


IWA_AGENT
System notification sent when an IGA agent disconnects or reconnects


LDAP_AGENT
System notification sent when an LDAP agent disconnects or reconnects


OKTA_ANNOUNCEMENT
Okta communication sent for announcements and release notes


OKTA_ISSUE
Okta communication sent for trust incident alerts and updates


OKTA_UPDATE
Okta communication sent for scheduled system updates


RATELIMIT_NOTIFICATION
System notification sent when an org reaches rate limit warning or violation thresholds


REPORT_SUSPICIOUS_ACTIVITY
System notification sent when a user reports suspicious activity


USER_DEPROVISION
System notification sent when a user is deprovisioned from apps


USER_LOCKED_OUT
System notification sent when a user is locked out from logging in to Okta


 
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/users/{userId}/subscriptions/{notificationType}
Request samples 
Response samples 
application/json
{
  • "channels": [
    • "string"
    ],
  • "notificationType": "AD_AGENT",
  • "status": "subscribed",
  • "_links": {
    • "self": {
      }
    }
}
Subscribe a user to a specific notification type
OAuth 2.0: okta.users.manage
Subscribes the current user to a specified notification type. Returns an AccessDeniedException message if requests are made for another user.


Request 
path Parameters
userId
required
string
The unique ID of the user


 
notificationType
required
string (NotificationType) 
The type of notification


 Enum: Description
AD_AGENT
System notification sent when an AD agent disconnects or reconnects


AGENT_AUTO_UPDATE_NOTIFICATION
System notification sent when an agent automatically updates


APP_IMPORT
System notification sent with the status of an app user import


CONNECTOR_AGENT
System notification sent when an on-premises provisioning or Okta on-prem MFA agent disconnects or reconnects


IWA_AGENT
System notification sent when an IGA agent disconnects or reconnects


LDAP_AGENT
System notification sent when an LDAP agent disconnects or reconnects


OKTA_ANNOUNCEMENT
Okta communication sent for announcements and release notes


OKTA_ISSUE
Okta communication sent for trust incident alerts and updates


OKTA_UPDATE
Okta communication sent for scheduled system updates


RATELIMIT_NOTIFICATION
System notification sent when an org reaches rate limit warning or violation thresholds


REPORT_SUSPICIOUS_ACTIVITY
System notification sent when a user reports suspicious activity


USER_DEPROVISION
System notification sent when a user is deprovisioned from apps


USER_LOCKED_OUT
System notification sent when a user is locked out from logging in to Okta


 
Responses 
200
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/subscriptions/{notificationType}/subscribe
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Unsubscribe a user from a specific notification type
OAuth 2.0: okta.users.manage
Unsubscribes the current user from a specified notification type. Returns an AccessDeniedException message if requests are made for another user.


Request 
path Parameters
userId
required
string
The unique ID of the user


 
notificationType
required
string (NotificationType) 
The type of notification


 Enum: Description
AD_AGENT
System notification sent when an AD agent disconnects or reconnects


AGENT_AUTO_UPDATE_NOTIFICATION
System notification sent when an agent automatically updates


APP_IMPORT
System notification sent with the status of an app user import


CONNECTOR_AGENT
System notification sent when an on-premises provisioning or Okta on-prem MFA agent disconnects or reconnects


IWA_AGENT
System notification sent when an IGA agent disconnects or reconnects


LDAP_AGENT
System notification sent when an LDAP agent disconnects or reconnects


OKTA_ANNOUNCEMENT
Okta communication sent for announcements and release notes


OKTA_ISSUE
Okta communication sent for trust incident alerts and updates


OKTA_UPDATE
Okta communication sent for scheduled system updates


RATELIMIT_NOTIFICATION
System notification sent when an org reaches rate limit warning or violation thresholds


REPORT_SUSPICIOUS_ACTIVITY
System notification sent when a user reports suspicious activity


USER_DEPROVISION
System notification sent when a user is deprovisioned from apps


USER_LOCKED_OUT
System notification sent when a user is locked out from logging in to Okta


 
Responses 
200
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/users/{userId}/subscriptions/{notificationType}/unsubscribe
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}