roles

GET

Retrieves all user Roles.

Auth. Required:

Yes

Roles Required:

None

Permissions Required:

ROLE:READ

Response Type:

Array

Request Structure

Table 392 Request Query Parameters

Name

Required

Description

id

no

Return only the Role identified by this integral, unique identifier

name

no

Return only the Role with this name

orderby

no

Choose the ordering of the results - must be the name of one of the fields of the objects in the response array

sortOrder

no

Changes the order of sorting. Either ascending (default or “asc”) or descending (“desc”)

limit

no

Choose the maximum number of results to return

offset

no

The number of results to skip before beginning to return results. Must use in conjunction with limit

page

no

Return the nth page of results, where “n” is the value of this parameter, pages are limit long and the first page is 1. If offset was defined, this query parameter has no effect. limit must be defined to make use of page.

#949 Request Example
GET /api/4.0/roles?name=read-only HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
Cookie: mojolicious=...

Response Structure

permissions:

An array of the names of the Permissions given to this Role

description:

A description of the Role

name:

The name of the Role

lastUpdated:

The date and time at which this Role was last updated, in RFC 3339 format

#950 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: TEDXlQqWMSnJbL10JtFdbw0nqciNpjc4bd6m7iAB8aymakWeF+ghs1k5LayjdzHcjeDE8UNF/HXSxOFvoLFEuA==
X-Server-Name: traffic_ops_golang/
Date: Wed, 25 Aug 2021 20:10:34 GMT
Content-Length: 888

{ "response": [
    {
        "name": "read-only",
        "description": "Has access to all read capabilities",
        "permissions": [
            "auth",
            "api-endpoints-read",
            "asns-read",
            "cache-config-files-read",
            "cache-groups-read",
            "capabilities-read",
            "cdns-read",
            "cdn-security-keys-read",
            "change-logs-read",
            "consistenthash-read",
            "coordinates-read",
            "delivery-services-read",
            "delivery-service-security-keys-read",
            "delivery-service-requests-read",
            "delivery-service-servers-read",
            "divisions-read",
            "to-extensions-read",
            "federations-read",
            "hwinfo-read",
            "jobs-read",
            "origins-read",
            "parameters-read",
            "phys-locations-read",
            "profiles-read",
            "regions-read",
            "roles-read",
            "server-capabilities-read",
            "servers-read",
            "service-categories-read",
            "stats-read",
            "statuses-read",
            "static-dns-entries-read",
            "steering-read",
            "steering-targets-read",
            "system-info-read",
            "tenants-read",
            "types-read",
            "users-read"
        ],
        "lastUpdated": "2021-05-03T14:50:18.93513-06:00",
    }
]}

POST

Creates a new Role.

Auth. Required:

Yes

Roles Required:

“admin”

Permissions Required:

ROLE:CREATE, ROLE:READ

Response Type:

Object

Request Structure

permissions:

An optional array of permission names that will be granted to the new Role[1]

description:

A helpful description of the Role’s purpose.

name:

The name of the new Role

#951 Request Example
POST /api/4.0/roles HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
Cookie: mojolicious=...
Content-Length: 56
Content-Type: application/json

{
    "name": "test",
    "description": "quest"
}

Response Structure

permissions:

An array of the names of the Permissions given to this Role

Tip

This can be null or empty, depending on whether it was present in the request body, or merely empty. Obviously, it can also be a populated array.

description:

A description of the Role

name:

The name of the Role

lastUpdated:

The date and time at which this Role was last updated, in RFC 3339 format

#952 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: gzfc7m/in5vVsVP+Y9h6JJfDhgpXKn9VAzoiPENhKbQfP8Q6jug08Rt2AK/3Nz1cx5zZ8P9IjVxDdIg7mlC8bw==
X-Server-Name: traffic_ops_golang/
Date: Wed, 04 Sep 2019 17:44:42 GMT
Content-Length: 128

{ "alerts": [{
    "text": "role was created.",
    "level": "success"
}],
"response": {
    "name": "test",
    "description": "quest",
    "permissions": null,
    "lastUpdated": "2021-05-03T14:50:18.93513-06:00"
}}

PUT

Replaces an existing Role with one provided by the request[2].

Auth. Required:

Yes

Roles Required:

“admin”

Permissions Required:

ROLE:UPDATE, ROLE:READ

Response Type:

Request Structure

Table 393 Request Query Parameters

Name

Required

Description

name

yes

The name of the Role to be updated

permissions:

An optional array of permission names that will be granted to the new Role

Warning

When not present, the affected Role’s Permissions will be unchanged - not removed, unlike when the array is empty.

description:

A helpful description of the Role’s purpose.

name:

The new name of the Role

#953 Request Example
PUT /api/4.0/roles?name=test HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
Cookie: mojolicious=...
Content-Length: 56
Content-Type: application/json

{
    "name":"test",
    "description": "quest_updated"
}

Response Structure

permissions:

An array of the names of the Permissions given to this Role

Tip

This can be null or empty, depending on whether it was present in the request body, or merely empty. Obviously, it can also be a populated array.

Warning

If no permissions array was given in the request, this will always be null, even if the Role has Permissions that would have gone unchanged.

description:

A description of the Role

name:

The name of the Role

lastUpdated:

The date and time at which this Role was last updated, in RFC 3339 format

#954 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: mlHQenE1Q3gjrIK2lC2hfueQOaTCpdYEfboN0A9vYPUIwTiaF5ZaAMPQBdfGyiAhgHRxowITs3bR7s1L++oFTQ==
X-Server-Name: traffic_ops_golang/
Date: Thu, 05 Sep 2019 12:56:46 GMT
Content-Length: 136

{
    "alerts": [
        {
            "text": "role was updated.",
            "level": "success"
        }
    ],
    "response": {
        "name": "test",
        "description": "quest_updated",
        "permissions": null,
        "lastUpdated": "2021-05-03T14:50:18.93513-06:00"
    }
}

DELETE

Deletes a Role[2].

Auth. Required:

Yes

Roles Required:

“admin”

Permissions Required:

ROLE:DELETE, ROLE:READ

Response Type:

undefined

Request Structure

Table 394 Request Query Parameters

Name

Required

Description

name

yes

The name of the Role to be deleted

#955 Request Example
DELETE /api/4.0/roles?name=test HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
Cookie: mojolicious=...

Response Structure

#956 Response Example
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Set-Cookie, Cookie
Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
Access-Control-Allow-Origin: *
Content-Type: application/json
Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54 GMT; Max-Age=3600; HttpOnly
Whole-Content-Sha512: 10jeFZihtbvAus/XyHAW8rhgS9JBD+X/ezCp1iExYkEcHxN4gjr1L6x8zDFXORueBSlFldgtbWKT7QsmwCHUWA==
X-Server-Name: traffic_ops_golang/
Date: Thu, 05 Sep 2019 13:02:06 GMT
Content-Length: 60

{ "alerts": [{
    "text": "role was deleted.",
    "level": "success"
}]}