Service Accounts

The Service Accounts API provides operations to manage SaaS or On-Prem Provisioning (OPP) app accounts as service accounts.

Note: This feature is available only if you're subscribed to Okta Privileged Access. Ensure that you've set up the Okta Privileged Access app before managing app accounts through this API.

See Manage service accounts.

List all app service accounts
Early Access
OAuth 2.0 scopes:
  • okta.serviceAccounts.read

Lists all app service accounts

Request
query Parameters
limit
integer [ 1 .. 200 ]
Default: 20

A limit on the number of objects to return

after
string

The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination.

match
string [ 3 .. 255 ] characters

Searches for app service accounts where the account name (name), username (username), app instance label (containerInstanceName), or OIN app key name (containerGlobalName) contains the given value

Example: match=salesforce
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

get/privileged-access/api/v1/service-accounts
Request samples 
Response samples 
application/json
[
  • {
    • "id": "a747a818-a4c4-4446-8a87-704216495a08",
    • "name": "salesforce Prod-1 account",
    • "description": "This is for accessing salesforce Prod-1",
    • "username": "testuser-salesforce-1@example.com",
    • "containerOrn": "orn:okta:idp:00o1n8sbwArJ7OQRw406:apps:salesforce:0oa1gjh63g214q0Hq0g4",
    • "containerInstanceName": "salesforce-1",
    • "containerGlobalName": "salesforce",
    • "ownerGroupIds": [
      ],
    • "ownerUserIds": [
      ],
    • "status": "NO_ISSUES",
    • "statusDetail": "ROTATED",
    • "created": "2024-04-04T15:56:05.000Z",
    • "lastUpdated": "2024-04-05T18:15:44.000Z"
    },
  • {
    • "id": "a747a818-a4c4-4446-8a87-704216495a09",
    • "name": "salesforce Prod-5 account",
    • "description": "This is for accessing salesforce Prod-5",
    • "username": "testuser-salesforce-5@example.com",
    • "containerOrn": "orn:okta:idp:00o1n8sbwArJ7OQRw406:apps:salesforce:0oa1gjh63g214q0Hq0g4",
    • "containerInstanceName": "salesforce-5",
    • "containerGlobalName": "salesforce",
    • "ownerGroupIds": [
      ],
    • "ownerUserIds": [
      ],
    • "status": "NO_ISSUES",
    • "statusDetail": "ROTATED",
    • "created": "2024-04-04T15:56:05.000Z",
    • "lastUpdated": "2024-04-05T18:15:44.000Z"
    }
]
Create an app service account
Early Access
OAuth 2.0 scopes: 
  • okta.serviceAccounts.manage
Creates a new app service account for managing an app account


Request 
Request Body schema: application/json
required
name
required
string <regex>   [ 1 .. 50 ] characters ^[\w\-_. ]+$
The user-defined name for the app service account


 
containerOrn
required
string
The ORN of the relevant resource.


Use the specific app ORN format (orn:{partition}:idp:{yourOrgId}:apps:{appType}:{appId}) to identify an Okta app instance in your org.


 
username
required
string  [ 1 .. 100 ] characters 
The username that serves as the direct link to your managed app account. Ensure that this value precisely matches the identifier of the target app account.


 
description
string <regex>   [ 0 .. 255 ] characters 
The description of the app service account


 
ownerGroupIds
Array of strings  [ 0 .. 10 ] items 
A list of IDs of the Okta groups who own the app service account


 
ownerUserIds
Array of strings  [ 0 .. 10 ] items 
A list of IDs of the Okta users who own the app service account


 
password
string <password> 
The app service account password. Required for apps that don't have provisioning enabled or don't support password synchronization.


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/privileged-access/api/v1/service-accounts
Request samples 
application/json
{
  • "containerOrn": "orn:okta:idp:00o1n8sbwArJ7OQRw406:apps:salesforce:0oa1gjh63g214q0Hq0g4",
  • "description": "This is for accessing salesforce Prod-5",
  • "name": "salesforce Prod-5 account",
  • "ownerGroupIds": [
    • "00g57qp78yZT2XBA40g7"
    ],
  • "ownerUserIds": [
    • "00u11s48P9zGW8yqm0g5"
    ],
  • "password": "pa$$word",
  • "username": "testuser-salesforce-5@example.com"
}
Response samples 
application/json
{
  • "containerGlobalName": "salesforce",
  • "containerInstanceName": "salesforce Prod 5",
  • "containerOrn": "orn:okta:idp:00o1n8sbwArJ7OQRw406:apps:salesforce:0oa1gjh63g214q0Hq0g4",
  • "created": "2019-08-24T14:15:22Z",
  • "description": "This is for accessing salesforce Prod-5",
  • "id": "a747a818-a4c4-4446-8a87-704216495a08",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "name": "salesforce Prod-5 account",
  • "ownerGroupIds": [
    • "00g57qp78yZT2XBA40g7"
    ],
  • "ownerUserIds": [
    • "00u11s48P9zGW8yqm0g5"
    ],
  • "status": "UNSECURED",
  • "statusDetail": "STAGED",
  • "username": "testuser-salesforce-5@example.com"
}
Retrieve an app service account
Early Access
OAuth 2.0 scopes: 
  • okta.serviceAccounts.read
Retrieves an app service account specified by ID


Request 
path Parameters
id
required
string
ID of an existing service account


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


get/privileged-access/api/v1/service-accounts/{id}
Request samples 
Response samples 
application/json
{
  • "containerGlobalName": "salesforce",
  • "containerInstanceName": "salesforce Prod 5",
  • "containerOrn": "orn:okta:idp:00o1n8sbwArJ7OQRw406:apps:salesforce:0oa1gjh63g214q0Hq0g4",
  • "created": "2019-08-24T14:15:22Z",
  • "description": "This is for accessing salesforce Prod-5",
  • "id": "a747a818-a4c4-4446-8a87-704216495a08",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "name": "salesforce Prod-5 account",
  • "ownerGroupIds": [
    • "00g57qp78yZT2XBA40g7"
    ],
  • "ownerUserIds": [
    • "00u11s48P9zGW8yqm0g5"
    ],
  • "status": "UNSECURED",
  • "statusDetail": "STAGED",
  • "username": "testuser-salesforce-5@example.com"
}
Update an existing app service account
Early Access
OAuth 2.0 scopes: 
  • okta.serviceAccounts.manage
Updates an existing app service account specified by ID


Request 
path Parameters
id
required
string
ID of an existing service account


 
Request Body schema: application/json
description
string <regex>   [ 0 .. 255 ] characters 
The description of the app service account


 
name
string <regex>   [ 1 .. 50 ] characters ^[\w\-_. ]+$
The user-defined name for the app service account


 
ownerGroupIds
Array of strings  [ 0 .. 10 ] items 
A list of IDs of the Okta groups who own the app service account


 
ownerUserIds
Array of strings  [ 0 .. 10 ] items 
A list of IDs of the Okta users who own the app service account


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


patch/privileged-access/api/v1/service-accounts/{id}
Request samples 
application/json
{
  • "description": "This is for accessing salesforce Prod-5",
  • "name": "salesforce Prod-5 account",
  • "ownerGroupIds": [
    • "00g57qp78yZT2XBA40g7"
    ],
  • "ownerUserIds": [
    • "00u11s48P9zGW8yqm0g5"
    ]
}
Response samples 
application/json
{
  • "containerGlobalName": "salesforce",
  • "containerInstanceName": "salesforce Prod 5",
  • "containerOrn": "orn:okta:idp:00o1n8sbwArJ7OQRw406:apps:salesforce:0oa1gjh63g214q0Hq0g4",
  • "created": "2019-08-24T14:15:22Z",
  • "description": "This is for accessing salesforce Prod-5",
  • "id": "a747a818-a4c4-4446-8a87-704216495a08",
  • "lastUpdated": "2019-08-24T14:15:22Z",
  • "name": "salesforce Prod-5 account",
  • "ownerGroupIds": [
    • "00g57qp78yZT2XBA40g7"
    ],
  • "ownerUserIds": [
    • "00u11s48P9zGW8yqm0g5"
    ],
  • "status": "UNSECURED",
  • "statusDetail": "STAGED",
  • "username": "testuser-salesforce-5@example.com"
}
Delete an app service account
Early Access
OAuth 2.0 scopes: 
  • okta.serviceAccounts.manage
Deletes an app service account specified by ID


Request 
path Parameters
id
required
string
ID of an existing service account


 
Responses 
204
No Content


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


delete/privileged-access/api/v1/service-accounts/{id}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}