Roles

Roles define permissions for the security services and can be associated with a user or API key

List roles

get/roles

Lists roles within an account

SecurityCloudOneApiKey
Request
query Parameters
cursor
string

An encoded value used to retrieve the next set of results for a query that returns more than limit results.

Example: cursor=3FDCA1955AE7EB167B25D7D90AC02B9
limit
integer

The maximum numbers of records to return. If zero, the request will use the default limit 25. If negative, the request will be rejected.

Example: limit=10
header Parameters
Api-Version
required
string

The API version used in this request.

Value: "v1"
Responses
200

The response body contains the roles.

400

Something about your request didn't quite make sense. The error message should help you figure out what went wrong.

401

Unauthorized

403

You tried to do something that you're not allowed to do. Check your privileges to see what you're actually allowed to do. This could also mean that your token has expired.

429

You have made too many requests too quickly. Check the Retry-After header for an indication of when you might be able to try again.

500

Something has gone terribly wrong. Sorry! The error message may help you figure out what went wrong, but it's unlikely that you'll be able to do anything about it unless you're the server administrator. It's possible that trying again will help, but it's more likely that you're out of luck for the moment.

503

The service is temporarily unavailable, likely due to maintenance. It should be available soon, check the Retry-After header for an indication of when you might be able to try again.

Response samples
application/json
{
  • "next": "dGhpcyB2YWx1ZSBpcyBvcGFxdWUsIGRlY29kaW5nIGl0IHdvbid0IGJlIHVzZWZ1bAo=",
  • "roles": [
    ]
}

Create a role

post/roles
SecurityCloudOneApiKey
Request
header Parameters
Api-Version
required
string

The API version used in this request.

Value: "v1"
Request Body schema: application/json
description
string

A description for the role.

id
string^[a-z0-9-]+$

The role's unique identifier

name
required
string

The role's name

serviceRoleURNs
required
Array of strings

A list of Role URNs associated with the role. Modifying this field replaces the entire array.

Responses
201

The role has been created.

400

Something about your request didn't quite make sense. The error message should help you figure out what went wrong.

401

Unauthorized

403

You tried to do something that you're not allowed to do. Check your privileges to see what you're actually allowed to do. This could also mean that your token has expired.

429

You have made too many requests too quickly. Check the Retry-After header for an indication of when you might be able to try again.

500

Something has gone terribly wrong. Sorry! The error message may help you figure out what went wrong, but it's unlikely that you'll be able to do anything about it unless you're the server administrator. It's possible that trying again will help, but it's more likely that you're out of luck for the moment.

503

The service is temporarily unavailable, likely due to maintenance. It should be available soon, check the Retry-After header for an indication of when you might be able to try again.

Request samples
application/json
{
  • "id": "full-access",
  • "name": "Full Access",
  • "description": "Full access to all security services and account management",
  • "serviceRoleURNs": [
    ]
}
Response samples
application/json
{
  • "id": "full-access",
  • "name": "Full Access",
  • "description": "Full access to all security services and account management",
  • "serviceRoleURNs": [
    ],
  • "created": "2020-06-21T09:01:12Z",
  • "lastModified": "2020-07-10T07:02:10Z",
  • "urn": "urn:cloudone:identity:ca-1:012345678912:role/full-access"
}

Describe a role

get/roles/{id}
SecurityCloudOneApiKey
Request
path Parameters
id
required
string^[a-z0-9-]+$

The role ID.

Example: full-access
header Parameters
Api-Version
required
string

The API version used in this request.

Value: "v1"
Responses
200

The response body contains the role details.

400

Something about your request didn't quite make sense. The error message should help you figure out what went wrong.

401

Unauthorized

403

You tried to do something that you're not allowed to do. Check your privileges to see what you're actually allowed to do. This could also mean that your token has expired.

404

The resource you were looking for doesn't exist.

429

You have made too many requests too quickly. Check the Retry-After header for an indication of when you might be able to try again.

500

Something has gone terribly wrong. Sorry! The error message may help you figure out what went wrong, but it's unlikely that you'll be able to do anything about it unless you're the server administrator. It's possible that trying again will help, but it's more likely that you're out of luck for the moment.

503

The service is temporarily unavailable, likely due to maintenance. It should be available soon, check the Retry-After header for an indication of when you might be able to try again.

Response samples
application/json
{
  • "id": "full-access",
  • "name": "Full Access",
  • "description": "Full access to all security services and account management",
  • "serviceRoleURNs": [
    ],
  • "created": "2020-06-21T09:01:12Z",
  • "lastModified": "2020-07-10T07:02:10Z",
  • "urn": "urn:cloudone:identity:ca-1:012345678912:role/full-access"
}

Modify a role

post/roles/{id}
SecurityCloudOneApiKey
Request
path Parameters
id
required
string^[a-z0-9-]+$

The role ID.

Example: full-access
header Parameters
Api-Version
required
string

The API version used in this request.

Value: "v1"
Request Body schema: application/json
description
string

A description for the role.

id
string^[a-z0-9-]+$

The role's unique identifier

name
required
string

The role's name

serviceRoleURNs
required
Array of strings

A list of Role URNs associated with the role. Modifying this field replaces the entire array.

Responses
200

The response body contains the role details.

400

Something about your request didn't quite make sense. The error message should help you figure out what went wrong.

401

Unauthorized

403

You tried to do something that you're not allowed to do. Check your privileges to see what you're actually allowed to do. This could also mean that your token has expired.

404

The resource you were looking for doesn't exist.

429

You have made too many requests too quickly. Check the Retry-After header for an indication of when you might be able to try again.

500

Something has gone terribly wrong. Sorry! The error message may help you figure out what went wrong, but it's unlikely that you'll be able to do anything about it unless you're the server administrator. It's possible that trying again will help, but it's more likely that you're out of luck for the moment.

503

The service is temporarily unavailable, likely due to maintenance. It should be available soon, check the Retry-After header for an indication of when you might be able to try again.

Request samples
application/json
{
  • "id": "full-access",
  • "name": "Full Access",
  • "description": "Full access to all security services and account management",
  • "serviceRoleURNs": [
    ]
}
Response samples
application/json
{
  • "id": "full-access",
  • "name": "Full Access",
  • "description": "Full access to all security services and account management",
  • "serviceRoleURNs": [
    ],
  • "created": "2020-06-21T09:01:12Z",
  • "lastModified": "2020-07-10T07:02:10Z",
  • "urn": "urn:cloudone:identity:ca-1:012345678912:role/full-access"
}

Delete a role

delete/roles/{id}
SecurityCloudOneApiKey
Request
path Parameters
id
required
string^[a-z0-9-]+$

The role ID.

Example: full-access
header Parameters
Api-Version
required
string

The API version used in this request.

Value: "v1"
Responses
204

The Role has been deleted.

400

Something about your request didn't quite make sense. The error message should help you figure out what went wrong.

401

Unauthorized

403

You tried to do something that you're not allowed to do. Check your privileges to see what you're actually allowed to do. This could also mean that your token has expired.

429

You have made too many requests too quickly. Check the Retry-After header for an indication of when you might be able to try again.

500

Something has gone terribly wrong. Sorry! The error message may help you figure out what went wrong, but it's unlikely that you'll be able to do anything about it unless you're the server administrator. It's possible that trying again will help, but it's more likely that you're out of luck for the moment.

503

The service is temporarily unavailable, likely due to maintenance. It should be available soon, check the Retry-After header for an indication of when you might be able to try again.

Response samples
application/json
{
  • "message": "Something went wrong."
}
➔ Next to API Keys