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

OK

get/v1/teams/{team_name}/cloud_connections
Request samples
Response samples
application/json
{
  • "list": [
    • {
      }
    ]
}

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

OK

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

OK

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

OK

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

OK

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

OK

get/v1/teams/{team_name}/cloud_entitlement_analyses
Request samples
Response samples
application/json
{
  • "list": [
    • {
      }
    ]
}

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

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> (?i)^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}...

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

OK

post/v1/teams/{team_name}/cloud_entitlement_analyses
Request samples
application/json
{
  • "account_ids": [
    • "012345678911",
    • "012345678912",
    • "012345678913",
    • "012345678914",
    • "012345678915",
    • "012345678916"
    ],
  • "analysis_rules": [
    • {
      }
    ],
  • "connection_id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
  • "discovery_rules": [
    • {
      }
    ],
  • "name": "US West 2 Prod"
}
Response samples
application/json
{
  • "account_ids": [
    • "012345678911",
    • "012345678912",
    • "012345678913",
    • "012345678914",
    • "012345678915",
    • "012345678916"
    ],
  • "analysis_rules": [
    • {
      }
    ],
  • "connection_id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
  • "created_at": "2023-08-25T12:00:00.000000Z",
  • "discovery_rules": [
    • {
      }
    ],
  • "id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
  • "name": "US West 2 Prod",
  • "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

OK

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": [
    • {
      }
    ],
  • "connection_id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
  • "created_at": "2023-08-25T12:00:00.000000Z",
  • "discovery_rules": [
    • {
      }
    ],
  • "id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
  • "name": "US West 2 Prod",
  • "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

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> (?i)^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}...

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

OK

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": [
    • {
      }
    ],
  • "connection_id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
  • "discovery_rules": [
    • {
      }
    ],
  • "name": "US West 2 Prod"
}
Response samples
application/json
{
  • "account_ids": [
    • "012345678911",
    • "012345678912",
    • "012345678913",
    • "012345678914",
    • "012345678915",
    • "012345678916"
    ],
  • "analysis_rules": [
    • {
      }
    ],
  • "connection_id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
  • "created_at": "2023-08-25T12:00:00.000000Z",
  • "discovery_rules": [
    • {
      }
    ],
  • "id": "5f3159e9-e7ab-428e-8a87-c2ebffe407f6",
  • "name": "US West 2 Prod",
  • "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 .. 12 ]

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 ]

An AWS group ID. Required if you set filter_by to group_id.

permission_set_arn
string [ 1 .. 2048 ]

An Amazon Resource Name (ARN) for your permission set. Required if you set filter_by to account_id_and_permission_set_arn.

Responses
200

OK

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": [
    • {
      }
    ]
}

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

OK

post/v1/teams/{team_name}/cloud_entitlement_analyses/{cloud_entitlement_analysis_id}/resources
Request samples
Response samples
application/json
{
  • "list": [
    • {
      }
    ]
}

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

OK

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": {
      },
    • "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

OK

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": {
      }
    },
  • "errors": {
    • "message": "string"
    },
  • "last_updated_at": "2023-08-25T12:00:00.000000Z",
  • "status": "ERROR"
}