Campaigns

Access certification campaigns allow key stakeholders to periodically review users’ access to resources. Okta can then modify resource access, based on stakeholder reviews. Manage campaign tasks with the following campaign APIs.

See Identity Governance for more information on Access Campaigns and Identity Governance.

Create a campaign
Beta
Admin permissions required: Access Certification Administrator
OAuth 2.0: okta.governance.accessCertifications.manage

Creates a campaign that governs whether the access can continue to exist.

When creating a campaign, you specify:

  • Which resource(s) are subject to review
  • Which user(s) with access to the resource(s) are subject to review
  • The schedule of the campaign (ONE_OFF)
  • Who should review access
  • What should be done after access is reviewed
  • If notifications should automatically be sent to a campaign creator or reviewer
Request
Request Body schema: application/json
required

Creates a single campaign with all the required characteristics

name
required
string [ 1 .. 255 ] characters

Name of the campaign. Maintain some uniqueness when naming the campaign as it helps to identify and filter for campaigns when needed.

required
object

Specify the action to be taken after a reviewer makes a decision to APPROVE or REVOKE the access, or if the campaign was CLOSED and there was no response from the reviewer.

required
object

Resource specific properties

required
object

Identifies the kind of reviewer for access certification.

  1. type = USER, where in a single reviewer reviews the whole campaign. The property reviewerId is required for that type.

  2. type = REVIEWER_EXPRESSION, where in, one can specify an expression to derive a reviewer for the whole campaign. The property fallBackReviewerId is required for that type. Specify fallBackReviewerId, if the system could not determine the reviewer using the expression. In such a case, the fallback reviewer specified via fallBackReviewerId would be automatic reviewer of the campaign. Behind the scenes, this type can represent reviews based on user manager as well. In such a case, the reviewer expression would be framed to indicate the user manager.

  3. type = GROUP, where in all the members of Okta group specified via reviewerGroupId becomes reviewers of the campaign. The property reviewerGroupId is required for that type. Note that, if the group specified via reviewerGroupId has only one member, then that reviewer will be assigned as a reviewer to all reviewers and type in those reviews changes to USER

  4. type = RESOURCE_OWNER, where in all the owners of Okta group becomes reviewers of the campaign. The property fallBackReviewerId is required for that type. For RESOURCE_OWNER to work, the property resourceSettings.type should be GROUP and resourceSettings.targetResources should be pointing to Okta group Id. The system, then derives all the owners of the groups specified via resourceSettings.targetResources.resourceId and assign them as reviewers to respective reviews of the campaign. Note that, if the system identifies that there is only one owner for such group(s) then that owner will be assigned as a reviewer to respective reviews and type in those reviews changes to USER. Specify fallBackReviewerId, if the system could not determine the reviewer using the group(s) specified via resourceSettings.targetResources.resourceId. In such a case, the fallback reviewer specified via fallBackReviewerId would be automatic reviewer of the campaign. Note that, if the provided Okta group has more than 10 members, when the campaign gets launched, only a max of 10 members will be pulled from the group. Those 10 members woud be the reviewers of the campaign. When fetching members of the group, there is no order guranteed. Additionally, if the Okta group specified has only one member, then that member will be assigned as a reviewer to all reviewers and type for those reviews changes to USER.

  5. type = MULTI_LEVEL, where in a campaign can be composed of more than one reviewer levels. The property reviewerLevels is required for that type. That means, it can be reviewed and passed on from reviewer at one level to the reviewer defined in the next level. This way more than more reviewer can decide on the reviews before making the final decision. Right now a max of two reviewer levels are supported. One has the flexibility to choose a combination of reviewers when defining the campaign. When a campaign is defined as multi level, only the property reviewerLevels is required. All other properties are ignored. Note that, if the provided Okta group has more than 10 owners, when the campaign gets launched, only a max of 10 owners will be pulled from the group. Those 10 owners woud be the reviewers of the campaign. When fetching owners of the group, there is no order guranteed. Additionally, if the Okta group specified has only one owners, then that owners will be assigned as a reviewer to all reviewers and type for those reviews changes to USER.

required
object

Scheduler specific settings.

A campaign can be a ONE_OFF or a RECURRING campaign.

You can't provide both in the campaign definition.

campaignType
string

Identifies if it is a resource campaign or a user campaign. By default it is RESOURCE.

Enum: "RESOURCE" "USER"
description
string <= 1000 characters

Human readable description.

object

Settings for email notifications to be sent to the reviewers at different stages of a campaign. All properties are optional.

object

User scope specific settings. If all the users of a resource under review are not part of the scope of certification, provide the scope of the user by means of a user expression.

Responses
201

A successful campaign create response

400

An invalid request to define a campaign

401

When authentication fails

403

When authorization fails

429

When the rate limit has been exceeded

500

When there is a server fault due to an unexpected error

post/governance/api/v1/campaigns
Request samples
application/json

The set of properties to pass when creating a campaign with resource as a group(s) and principle scope settings that apply on the resource.

{
  • "name": "Monthly access review of sales team",
  • "description": "Review access of all sales team members to a specific app",
  • "scheduleSettings": {
    • "type": "ONE_OFF",
    • "startDate": "2022-06-01T00:00:01.001Z",
    • "durationInDays": 30,
    • "timeZone": "America/Los_Angeles"
    },
  • "resourceSettings": {
    • "type": "GROUP",
    • "targetResources": [
      • {
        },
      • {
        }
      ]
    },
  • "principalScopeSettings": {
    • "type": "USERS"
    },
  • "reviewerSettings": {
    • "type": "USER",
    • "reviewerId": "00ub0oNGTSWTBKOLGLNR",
    • "selfReviewDisabled": true
    },
  • "remediationSettings": {
    • "accessApproved": "NO_ACTION",
    • "accessRevoked": "NO_ACTION",
    • "noResponse": "NO_ACTION"
    }
}
Response samples
application/json

The set of properties to pass when creating a campaign with resource as a group(s) and principle scope settings that apply on the resource.

{}

List all campaigns
Beta
Admin permissions required: Access Certification Administrator
OAuth 2.0: okta.governance.accessCertifications.read

Lists all or a subset of campaigns in your organization.

Use the ?filter= parameter to narrow results with the following campaign properties - name, status, scheduleType, reviewerType and recurringCampaignId.

Use the ?orderBy= parameter to get ordered results with the following campaign properties - name, created, startDate, endDate, and status.

By default, results are sorted by created.

Request
query Parameters
after
string

The after cursor provided by a prior request.

filter
string

Apply various filters by using supported campaign filtering properties.

Note: Query parameter percent encoding is required. See Percent-encoding

Examples:
Query param: ?filter=name eq "Sales Review"
filter=name%20eq%20%22Sales%20Review%22
Query param: ?filter=status eq "SCHEDULED"
filter=status%20eq%20%22SCHEDULED%22
Query param: ?filter=status eq "COMPLETED" OR status eq "SCHEDULED"
filter=status%20eq%20%22COMPLETED%22%20OR%20status%20eq%20%22SCHEDULED%22
Query param: ?filter=startDate gt "2022-05-24T14:15:22Z"
filter=startDate%20gt%20%222022-05-24T14%3A15%3A22Z%22
Query param: ?filter=endDate gt "2022-05-24T14:15:22Z"
filter=endDate%20gt%20%222022-05-24T14%3A15%3A22Z%22
Query param: ?filter=scheduleType eq "ONE_OFF"
filter=scheduleType%20eq%20ONE_OFF
Query param: ?filter=scheduleType eq "RECURRING"
filter=scheduleType%20eq%20RECURRING
Query param: ?filter=reviewerType eq "USER"
filter=reviewerType%20eq%20USER
Query param: ?filter=reviewerType eq "GROUP"
filter=reviewerType%20eq%20GROUP
Query param: ?filter=reviewerType eq "RESOURCE_OWNER"
filter=reviewerType%20eq%20RESOURCE_OWNER
Query param: ?filter=reviewerType eq "MULTI_LEVEL"
filter=reviewerType%20eq%20MULTI_LEVEL
Query param: ?filter=recurringCampaignId eq "icijNW29nev6qyksD0g1"
filter=recurringCampaignId%20eq%20%22icijNW29nev6qyksD0g1%22
limit
integer [ 1 .. 200 ]
Default: 20

The maximum number of records that will be returned in a given result.

orderBy
Array of strings = 1 items
Default: ["created asc"]

Apply an ordering of campaigns by specifying a supported campaign property name with %20asc or %20desc suffix.

Note: Query parameter percent encoding is required. See Percent-encoding

Examples:
Query param: ?orderBy=name desc
orderBy=name%20desc
Query param: ?orderBy=created desc
orderBy=created%20desc
Query param: ?orderBy=startDate desc
orderBy=startDate%20desc
Query param: ?orderBy=endDate desc
orderBy=endDate%20desc
Query param: ?orderBy=status desc
orderBy=status%20desc
Responses
200

A successful campaign list response

400

An invalid list request

401

When authentication fails

403

When authorization fails

429

When the rate limit has been exceeded

500

When there is a server fault due to an unexpected error

get/governance/api/v1/campaigns
Request samples 
Response samples 
application/json
The list of campaigns which is filtered by specific name of the campaign


{}
Retrieve a campaign
Beta
Admin permissions required: Access Certification Administrator
OAuth 2.0: okta.governance.accessCertifications.read
Retrieves the full representation of a specific campaign.


More information is returned than the abbreviated representation in a List campaigns operation.


Request 
path Parameters
campaignId
required
string
The id of the campaign


 
Responses 
200
A successful campaign list response


401
When authentication fails


403
When authorization fails


404
When the requested resource was not found


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


get/governance/api/v1/campaigns/{campaignId}
Request samples 
Response samples 
application/json
Get the campaign by Id that is in scheduled state


{}
Delete a campaign
Beta
Admin permissions required: Access Certification Administrator
OAuth 2.0: okta.governance.accessCertifications.manage
Deletes a campaign from your organization. 


Only campaigns with a status of SCHEDULED or ERROR can be deleted. Attempting this operation with campaigns in any other status yields a 409 Conflict response indicating the state of the campaign is incompatible with the delete operation.


If the campaign being deleted has a schedule type RECURRING, then any occurence of future campaigns as per recurring schedule, will not happen.




Note: There is a limit on the number of campaigns with a status of SCHEDULED. Deleting campaigns that are never meant to be launched (whether through the launch operation or automatically through scheduleSettings), can be useful to remain under this limit.




Request 
path Parameters
campaignId
required
string
The id of the campaign


 
Responses 
204
A successful campaign delete response


401
When authentication fails


403
When authorization fails


404
When the requested resource was not found


409
When attempting to perform an operation on a recurring, non-SCHEDULED, or non-ERROR campaign.


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


delete/governance/api/v1/campaigns/{campaignId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000004",
  • "errorSummary": "Authentication failed.",
  • "errorLink": "E0000004",
  • "errorId": "oaeWCGz73hpRCG75VHP6-RRXw",
  • "errorCauses": [ ]
}
Launch a campaign
Beta
Admin permissions required: Access Certification Administrator
OAuth 2.0: okta.governance.accessCertifications.manage
Launches a campaign to initiate the assignment of reviews to reviewers, regardless of pre-configured scheduleSettings.


Only campaigns with a status of SCHEDULED can be launched. A valid launch operation transitions a campaign to a status of ACTIVE.


If the campaign being launched has a recurring schedule, then it launches the next occurence of the campaign as per the schedule.


Attempting this operation with campaigns in any other status yields a 409 Conflict response indicating the state of the campaign is incompatible with the launch operation.


If the campaign being launched has a recurring definition, on successful response, one should get the newly launched campaign resource endpoint in HTTP header location.




Note: This operation is optional. Typically, campaigns are launched automatically according to the campaign's schedule settings (scheduleSettings).




Request 
path Parameters
campaignId
required
string
The id of the campaign


 
Responses 
202
A successful campaign launch response


401
When authentication fails


403
When authorization fails


404
When the requested resource was not found


409
When attempting to perform an operation on a recurring or non SCHEDULED campaign.


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


post/governance/api/v1/campaigns/{campaignId}/launch
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000004",
  • "errorSummary": "Authentication failed.",
  • "errorLink": "E0000004",
  • "errorId": "oaeWCGz73hpRCG75VHP6-RRXw",
  • "errorCauses": [ ]
}
End a campaign
Beta
Admin permissions required: Access Certification Administrator
OAuth 2.0: okta.governance.accessCertifications.manage
Ends a campaign before its scheduled end date (from scheduleSettings).


This operation closes any open reviews and prevents any further review activity, such as decisions or reassignments. Reviews associated with the campaign are remediated, if the remediation setting for the campaign is set.


Only campaigns with a status of ACTIVE can be completed. A valid end operation transitions a campaign to a status of COMPLETED. Attempting this operation with campaigns in any other status yields a 409 Conflict response indicating the state of the campaign is incompatible with the end campaign operation.




Note: This operation is optional. Typically, campaigns are completed automatically according to the campaign's schedule settings scheduleSettings.




Request 
path Parameters
campaignId
required
string
The id of the campaign


 
Request Body schema: application/json
optional
Ends a campaign with the option to skip remediation.


skipRemediation
boolean
Set the Boolean variable to true to skip remediation in cases where remediationSetting.noResponse=DENY.


 
Responses 
202
A successful campaign complete response


401
When authentication fails


403
When authorization fails


404
When the requested resource was not found


409
When the campaign status is not ACTIVE.


429
When the rate limit has been exceeded


500
When there is a server fault due to an unexpected error


post/governance/api/v1/campaigns/{campaignId}/end
Request samples 
application/json
{
  • "skipRemediation": false
}
Response samples 
application/json
{
  • "errorCode": "E0000004",
  • "errorSummary": "Authentication failed.",
  • "errorLink": "E0000004",
  • "errorId": "oaeWCGz73hpRCG75VHP6-RRXw",
  • "errorCauses": [ ]
}