Cloud Infrastructure Entitlements

The Cloud Infrastructure Entitlements API automatically determines which cloud infrastructure resources are accessible to users through entitlements. This feature enables OPA admins to determine the risks to high-value resources in their cloud infrastructure applications and take measures to remediate those risks.

See Cloud infrastructure entitlement discovery and analysis.

Currently, this feature only supports AWS and allows Teams to analyze entitlements that grant end user access to Amazon Relational Database Service (RDS).

List all Cloud Connections

Lists all existing Cloud Connections

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name

required

string

The name of your Team

Responses

200

get/v1/teams/{team_name}/cloud_connections

Request samples

Response samples

application/json

{"list": [{"cloud_connection_details": {"account_id": "123456789012",
"external_id": "b4c617de-d58e-4d47-bbdf-c3a3db98ed3d",
"role_arn": "arn:aws:iam::000000000000:role/example"
},
"id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"name": "APAC-1",
"provider": "aws"
}
]
}

Create a Cloud Connection

Creates a connection to a specified cloud provider. Currently, this only supports AWS.

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name

required

string

The name of your Team

Request Body schema: application/json

object (CloudConnectionDetails)

account_id required	string = 12 characters An AWS account ID
external_id required	string A UUID generated by OPA. You can access this from the OPA Dashboard.
role_arn required	string An Amazon Resource Name (ARN) for the role. The Cloud Connection uses this role to access the associated AWS account.

name

string <regex> [ 1 .. 255 ] characters ^[\w\-_.]+$

The name of the Cloud Connection

provider

string (CloudConnectionProvider)

The cloud provider associated with the Cloud Connection. Currently, only accepts aws.

Value: "aws"

Responses

201

Created

post/v1/teams/{team_name}/cloud_connections

Request samples

application/json

{"cloud_connection_details": {"account_id": "123456789012",
"external_id": "b4c617de-d58e-4d47-bbdf-c3a3db98ed3d",
"role_arn": "arn:aws:iam::000000000000:role/example"
},
"name": "APAC-1",
"provider": "aws"
}

Response samples

application/json

{"cloud_connection_details": {"account_id": "123456789012",
"external_id": "b4c617de-d58e-4d47-bbdf-c3a3db98ed3d",
"role_arn": "arn:aws:iam::000000000000:role/example"
},
"id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"name": "APAC-1",
"provider": "aws"
}

Check a Cloud Connection

Checks an existing Cloud Connection.

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name

required

string

The name of your Team

Request Body schema: application/json

required

object (CloudConnectionDetails)

account_id required	string = 12 characters An AWS account ID
external_id required	string A UUID generated by OPA. You can access this from the OPA Dashboard.
role_arn required	string An Amazon Resource Name (ARN) for the role. The Cloud Connection uses this role to access the associated AWS account.

provider

required

string (CloudConnectionProvider)

The cloud provider associated with the Cloud Connection. Currently, only accepts aws.

Value: "aws"

Responses

200

post/v1/teams/{team_name}/cloud_connections/check

Request samples

application/json

{"cloud_connection_details": {"account_id": "123456789012",
"external_id": "b4c617de-d58e-4d47-bbdf-c3a3db98ed3d",
"role_arn": "arn:aws:iam::000000000000:role/example"
},
"provider": "aws"
}

Response samples

application/json

{"details": "string",
"status": "success"
}

Retrieve a Cloud Connection

Retrieves an existing Cloud Connection

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
connection_id required	string The UUID of a Cloud Connection

Responses

200

get/v1/teams/{team_name}/cloud_connections/{connection_id}

Request samples

Response samples

application/json

{"cloud_connection_details": {"account_id": "123456789012",
"external_id": "b4c617de-d58e-4d47-bbdf-c3a3db98ed3d",
"role_arn": "arn:aws:iam::000000000000:role/example"
},
"id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"name": "APAC-1",
"provider": "aws"
}

Update a Cloud Connection

Updates an existing Cloud Connection

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
connection_id required	string The UUID of a Cloud Connection

Request Body schema: application/json

required

object (UpdateCloudConnectionDetails)

account_id required	string = 12 characters An AWS account ID
role_arn required	string An AWS role ARN. The Cloud Connection will use this role to access the associated AWS account.

name

required

string <regex> [ 1 .. 255 ] characters ^[\w\-_.]+$

The name of the Cloud Connection

provider

required

string (CloudConnectionProvider)

The cloud provider associated with the Cloud Connection. Currently, only accepts aws.

Value: "aws"

Responses

200

put/v1/teams/{team_name}/cloud_connections/{connection_id}

Request samples

application/json

{"cloud_connection_details": {"account_id": "123456789012",
"role_arn": "arn:aws:iam::000000000000:role/example"
},
"name": "APAC-1",
"provider": "aws"
}

Response samples

application/json

{"cloud_connection_details": {"account_id": "123456789012",
"external_id": "b4c617de-d58e-4d47-bbdf-c3a3db98ed3d",
"role_arn": "arn:aws:iam::000000000000:role/example"
},
"id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"name": "APAC-1",
"provider": "aws"
}

Delete a Cloud Connection

Deletes an existing Cloud Connection

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
connection_id required	string The UUID of a Cloud Connection

Responses

204

No Content

delete/v1/teams/{team_name}/cloud_connections/{connection_id}

Request samples

List all accounts for a Cloud Connection

Lists all accounts for a specified Cloud Connection. This is used to run Entitlement Analysis jobs.

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
connection_id required	string The UUID of a Cloud Connection

Responses

200

get/v1/teams/{team_name}/cloud_connections/{connection_id}/accounts

Request samples

Response samples

application/json

{"account_id": ["012345678911",
"012345678912",
"012345678913",
"012345678914",
"012345678915",
"012345678916"
]
}

List all Cloud Entitlement Jobs

Lists all Cloud Entitlement Jobs.

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name

required

string

The name of your Team

Responses

200

get/v1/teams/{team_name}/cloud_entitlement_analyses

Request samples

Response samples

application/json

{"list": [{"account_ids": ["012345678911",
"012345678912",
"012345678913",
"012345678914",
"012345678915",
"012345678916"
],
"analysis_rules": [{"rules": {"excessive_user_access": "10"
}
},
{"rules": {"excessive_group_access": "10"
}
}
],
"connection_id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"created_at": "2023-08-25T12:00:00.000000Z",
"discovery_rules": [{"resource_details": {"type": "rds",
"action": ["rds-db:connect"
]
},
"rules": {"resource_name_pattern": "*"
}
}
],
"id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"name": "CloudEntitlementJob",
"status": "COMPLETED",
"updated_at": "2023-08-25T12:00:00.000000Z"
}
]
}

Create a Cloud Entitlement Job

Creates a Cloud Entitlement Job

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name

required

string

The name of your Team

Request Body schema: application/json

account_ids

required

Array of strings <= 10 items

A list of accounts associated with the specified Cloud Connection

required

Array of objects (CloudEntitlementJobAnalysis)

Conditions used to define risk thresholds for this job

Array

required

object

The specific properties used to filter the discovered resources

connection_id

required

string <regex> ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-...

The ID of an existing Cloud Connection

required

Array of objects (CloudEntitlementJobDiscovery)

The rules that control which resources are returned by the job

Array

required	object The specific details that define how the job discovers resources
required	object The specific rules that define how the job discovers resources

name

required

string <regex> [ 1 .. 255 ] characters ^[\w\-_.]+$

The name of the job

Responses

200

post/v1/teams/{team_name}/cloud_entitlement_analyses

Request samples

application/json

{"account_ids": ["012345678911",
"012345678912",
"012345678913",
"012345678914",
"012345678915",
"012345678916"
],
"analysis_rules": [{"rules": {"excessive_user_access": "10"
}
},
{"rules": {"excessive_group_access": "10"
}
}
],
"connection_id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"discovery_rules": [{"resource_details": {"type": "rds",
"action": ["rds-db:connect"
]
},
"rules": {"resource_name_pattern": "*"
}
}
],
"name": "CloudEntitlementJob"
}

Response samples

application/json

{"account_ids": ["012345678911",
"012345678912",
"012345678913",
"012345678914",
"012345678915",
"012345678916"
],
"analysis_rules": [{"rules": {"excessive_user_access": "10"
}
},
{"rules": {"excessive_group_access": "10"
}
}
],
"connection_id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"created_at": "2023-08-25T12:00:00.000000Z",
"discovery_rules": [{"resource_details": {"type": "rds",
"action": ["rds-db:connect"
]
},
"rules": {"resource_name_pattern": "*"
}
}
],
"id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"name": "CloudEntitlementJob",
"status": "COMPLETED",
"updated_at": "2023-08-25T12:00:00.000000Z"
}

Retrieve a Cloud Entitlement Job

Retrieves a specified Cloud Entitlement Job

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
cloud_entitlement_analysis_id required	string The UUID of a Cloud Entitlement Job

Responses

200

get/v1/teams/{team_name}/cloud_entitlement_analyses/{cloud_entitlement_analysis_id}

Request samples

Response samples

application/json

{"account_ids": ["012345678911",
"012345678912",
"012345678913",
"012345678914",
"012345678915",
"012345678916"
],
"analysis_rules": [{"rules": {"excessive_user_access": "10"
}
},
{"rules": {"excessive_group_access": "10"
}
}
],
"connection_id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"created_at": "2023-08-25T12:00:00.000000Z",
"discovery_rules": [{"resource_details": {"type": "rds",
"action": ["rds-db:connect"
]
},
"rules": {"resource_name_pattern": "*"
}
}
],
"id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"name": "CloudEntitlementJob",
"status": "COMPLETED",
"updated_at": "2023-08-25T12:00:00.000000Z"
}

Update a Cloud Entitlement Job

Updates an existing Cloud Entitlement Job

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
cloud_entitlement_analysis_id required	string The UUID of a Cloud Entitlement Job

Request Body schema: application/json

account_ids

required

Array of strings <= 10 items

A list of accounts associated with the specified Cloud Connection

required

Array of objects (CloudEntitlementJobAnalysis)

Conditions used to define risk thresholds for this job

Array

required

object

The specific properties used to filter the discovered resources

connection_id

required

string <regex> ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-...

The ID of an existing Cloud Connection

required

Array of objects (CloudEntitlementJobDiscovery)

The rules that control which resources are returned by the job

Array

required	object The specific details that define how the job discovers resources
required	object The specific rules that define how the job discovers resources

name

required

string <regex> [ 1 .. 255 ] characters ^[\w\-_.]+$

The name of the job

Responses

200

put/v1/teams/{team_name}/cloud_entitlement_analyses/{cloud_entitlement_analysis_id}

Request samples

application/json

{"account_ids": ["012345678911",
"012345678912",
"012345678913",
"012345678914",
"012345678915",
"012345678916"
],
"analysis_rules": [{"rules": {"excessive_user_access": "10"
}
},
{"rules": {"excessive_group_access": "10"
}
}
],
"connection_id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"discovery_rules": [{"resource_details": {"type": "rds",
"action": ["rds-db:connect"
]
},
"rules": {"resource_name_pattern": "*"
}
}
],
"name": "CloudEntitlementJob"
}

Response samples

application/json

{"account_ids": ["012345678911",
"012345678912",
"012345678913",
"012345678914",
"012345678915",
"012345678916"
],
"analysis_rules": [{"rules": {"excessive_user_access": "10"
}
},
{"rules": {"excessive_group_access": "10"
}
}
],
"connection_id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"created_at": "2023-08-25T12:00:00.000000Z",
"discovery_rules": [{"resource_details": {"type": "rds",
"action": ["rds-db:connect"
]
},
"rules": {"resource_name_pattern": "*"
}
}
],
"id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"name": "CloudEntitlementJob",
"status": "COMPLETED",
"updated_at": "2023-08-25T12:00:00.000000Z"
}

Delete a Cloud Entitlement Job

Deletes an existing Cloud Entitlement Job

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
cloud_entitlement_analysis_id required	string The UUID of a Cloud Entitlement Job

Responses

204

No Content

delete/v1/teams/{team_name}/cloud_entitlement_analyses/{cloud_entitlement_analysis_id}

Request samples

List all Assigned Users for a Cloud Entitlement Job

Lists all assigned users discovered by a Cloud Entitlement Job. You can filter by users assigned to a specific group or by users associated with a specific permission set within an account.

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
cloud_entitlement_analysis_id required	string The UUID of a Cloud Entitlement Job

Request Body schema: application/json

account_id	string = 12 characters An AWS account ID. Required if you set `filter_by` to `account_id_and_permission_set_arn`.
filter_by required	string Whether to list users assigned to a specific group or associated with a specific permission set ARN Enum: "group_id" "account_id_and_permission_set_arn"
group_id	string [ 1 .. 64 ] characters An AWS group ID. Required if you set `filter_by` to `group_id`.
permission_set_arn	string [ 1 .. 2048 ] characters An Amazon Resource Name (ARN) for your permission set. Required if you set `filter_by` to `account_id_and_permission_set_arn`.

Responses

200

post/v1/teams/{team_name}/cloud_entitlement_analyses/{cloud_entitlement_analysis_id}/list_users

Request samples

application/json

{"account_id": "123456789012",
"filter_by": "group_id",
"group_id": "AGPA00000000",
"permission_set_arn": "arn:${Partition}:sso:::permissionSet/${InstanceId}/${PermissionSetId}"
}

Response samples

application/json

{"list": [{"created_at": "2023-08-25T12:00:00.000000Z",
"id": "a747a818-a4c4-4446-8a87-704216495a08",
"updated_at": "2023-08-25T12:00:00.000000Z",
"user_details": {"user_name": "Todd",
"primary_email": "string",
"display_name": "string"
},
"user_id": "string"
}
]
}

List all Resources for a Cloud Entitlement Job

Lists all resources discovered by a Cloud Entitlement Job. This list is sorted by risk.

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
cloud_entitlement_analysis_id required	string The UUID of a Cloud Entitlement Job

Responses

200

post/v1/teams/{team_name}/cloud_entitlement_analyses/{cloud_entitlement_analysis_id}/resources

Request samples

Response samples

application/json

{"list": [{"at_risk": true,
"details": {"name": "string",
"account_id": "123456789012",
"region": "string",
"aws_id": "string",
"arn": "string",
"resource_id": "string",
"resource_type": "rds",
"org_details": {"orgid": "string",
"name": "string"
},
"children": [{"id": "string",
"name": "string",
"arn": "string",
"children": [{ }
]
}
]
},
"id": "string"
}
]
}

Retrieve a Resource from a Cloud Entitlement Job

Retrieves a specified Resource from a Cloud Entitlement Job

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
cloud_entitlement_analysis_id required	string The UUID of a Cloud Entitlement Job
cloud_entitlement_summary_param required	string A specific param within a Cloud Entitlement Job

Responses

200

get/v1/teams/{team_name}/cloud_entitlement_analyses/{cloud_entitlement_analysis_id}/resources/{cloud_entitlement_summary_param}

Request samples

Response samples

application/json

{"at_risk": true,
"details": {"name": "string",
"account_id": "123456789012",
"region": "string",
"aws_id": "string",
"arn": "string",
"resource_id": "string",
"resource_type": "rds",
"org_details": {"orgid": "string",
"name": "string"
},
"children": [{"id": "string",
"name": "string",
"arn": "string",
"children": [{ }
]
}
]
},
"id": "string"
}

Run a Cloud Entitlement Job

Runs the specified Cloud Entitlement Job

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
cloud_entitlement_analysis_id required	string The UUID of a Cloud Entitlement Job

Responses

204

No Content

post/v1/teams/{team_name}/cloud_entitlement_analyses/{cloud_entitlement_analysis_id}/run

Request samples

Retrieve a Cloud Entitlement Job Summary

Retrieves a high-level summary of a previously run Cloud Entitlement Job. If the specified job doesn't have a status of COMPLETED or ERROR, this operation returns an empty response.

This endpoint requires the following role: resource_admin.

SecuritybearerAuth

Request

path Parameters

team_name required	string The name of your Team
cloud_entitlement_analysis_id required	string The UUID of a Cloud Entitlement Job

Responses

200

post/v1/teams/{team_name}/cloud_entitlement_analyses/{cloud_entitlement_analysis_id}/summary

Request samples

Response samples

application/json

{"details": {"resource_type": "rds",
"resource_total_count": "string",
"resources_at_risk_count": 0,
"organization": {"id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
"name": "US West 2 Prod"
}
},
"errors": {"message": "string"
},
"last_updated_at": "2023-08-25T12:00:00.000000Z",
"status": "ERROR"
}

Social
CONTACT & LEGAL
MORE INFORMATION
okta.com
Products, case studies, resources
Help Center
Knowledgebase, roadmaps, and more
Trust
System status, security, compliance