Users

/api/1.2/users

GET /api/1.2/users

Retrieves all users.

Authentication Required: Yes

Role(s) Required: None

Request Query Parameters

Name Required Description
tenant no Filter users by tenant ID.

Response Properties

Parameter Type Description
addressLine1 string  
addressLine2 string  
city string  
company string  
country string  
email string  
fullName string  
gid string  
id hash  
lastUpdated string  
newUser string  
phoneNumber string  
postalCode string  
publicSshKey string  
registrationSent string  
role string  
roleName string  
stateOrProvince string  
tenant string Owning tenant name
tenantId int Owning tenant ID
uid string  
username string  

Response Example

{
   "response": [
              {
                     "addressLine1": "",
                     "addressLine2": "",
                     "city": "",
                     "company": "",
                     "country": "",
                     "email": "email1@email.com",
                     "fullName": "Tom Simpson",
                     "gid": "0",
                     "id": "53",
                     "lastUpdated": "2016-01-26 10:22:07",
                     "newUser": true,
                     "phoneNumber": "",
                     "postalCode": "",
                     "publicSshKey": "xxx",
                     "registrationSent": true,
                     "role": "6",
                     "rolename": "admin",
                     "stateOrProvince": "",
                     "tenant": "root",
                     "tenantId": 1,
                     "uid": "0",
                     "username": "tsimpson"
              },
              {
                     ... more users
              },
     ]
 }

GET /api/1.2/users/:id

Retrieves user by ID.

Authentication Required: Yes

Role(s) Required: None

Request Route Parameters

Name Required Description
id yes User id.

Response Properties

Parameter Type Description
addressLine1 string  
addressLine2 string  
city string  
company string  
country string  
email string  
fullName string  
gid string  
id hash  
lastUpdated string  
newUser string  
phoneNumber string  
postalCode string  
publicSshKey string  
registrationSent string  
role string  
roleName string  
stateOrProvince string  
tenant string Owning tenant name
tenantId int Owning tenant ID
uid string  
username string  

Response Example

{
   "response": [
              {
                     "addressLine1": "",
                     "addressLine2": "",
                     "city": "",
                     "company": "",
                     "country": "",
                     "email": "email1@email.com",
                     "fullName": "Tom Simpson",
                     "gid": "0",
                     "id": "53",
                     "lastUpdated": "2016-01-26 10:22:07",
                     "newUser": true,
                     "phoneNumber": "",
                     "postalCode": "",
                     "publicSshKey": "xxx",
                     "registrationSent": true,
                     "role": "6",
                     "rolename": "admin",
                     "stateOrProvince": "",
                     "tenant": "root",
                     "tenantId": 1,
                     "uid": "0",
                     "username": "tsimpson"
              },
              {
                     ... more users
              },
     ]
 }

POST /api/1.2/users

Create a user.

Authentication Required: Yes

Role(s) Required: admin or oper

Request Properties

Parameter Type Required Description
addressLine1 string no  
addressLine2 string no  
city string no  
confirmLocalPassword string yes  
company string no  
country string no  
email string yes  
fullName string yes  
localPassword string yes  
newUser bool no  
phoneNumber string no  
postalCode string no  
publicSshKey string no  
role int yes  
stateOrProvince string no  
tenantId int no Owning tenant ID
username string yes  

Request Example

{
    "username": "tsimpson"
    "tenantId": 1,
    "fullName": "Tom Simpson"
    "email": "email1@email.com"
    "role": 6
    "localPassword": "password"
    "confirmLocalPassword": "password"
}

Response Properties

Parameter Type Description
addressLine1 string  
addressLine2 string  
city string  
company string  
country string  
email string  
fullName string  
gid int  
id int  
lastUpdated string  
newUser string  
phoneNumber string  
postalCode string  
publicSshKey string  
registrationSent bool  
role int  
roleName string  
stateOrProvince string  
uid int  
tenantId int Owning tenant ID
username string  

Response Example

 {"alerts": [
          {
              "level":"success",
              "text":"User creation was successful."
          }
      ],
  "response: {
          "addressLine1":"",
          "addressLine2":"",
          "city":"",
          "company":"",
          "country":"",
          "email":"email1@email.com",
          "fullName":"Tom Simpson",
          "gid":0,
          "id":2,
          "lastUpdated":null,
          "newUser":false,
          "phoneNumber":"",
          "postalCode":"",
          "publicSshKey":"",
          "registrationSent":false,
          "role":6,
          "roleName":"portal",
          "stateOrProvince":"",
          "tenantId": 1,
          "uid":0,
          "username":"tsimpson",
      }
}

POST /api/1.2/users/register

Register a user and send registration email.

Authentication Required: Yes

Role(s) Required: Admin or Operations

Request Properties

Parameter Type Required Description
email string yes Email address of the new user.
role int yes Role ID of the new user.
tenantId int yes Tenant ID of the new user.

Request Example

{
    "email": "foo@bar.com"
    "role": 1,
    "tenantId": "1"
}

Response Example

{
    "alerts": [
         {
             "level":"success",
             "text":"Sent user registration to foo@bar.com with the following permissions [ role: admin | tenant: root ]"
         }
     ]
 }

GET /api/1.2/users/:id/deliveryservices

Retrieves all delivery services assigned to the user. See also Using Traffic Ops - Delivery Service.

Authentication Required: Yes

Role(s) Required: None

Request Route Parameters

Name Required Description
id yes User ID.

Response Properties

Parameter Type Description
active bool true if active, false if inactive.
cacheurl string Cache URL rule to apply to this delivery service.
ccrDnsTtl string The TTL of the DNS response for A or AAAA queries requesting the IP address of the tr. host.
cdnId string Id of the CDN to which the delivery service belongs to.
cdnName string Name of the CDN to which the delivery service belongs to.
checkPath string The path portion of the URL to check this deliveryservice for health.
deepCachingType string

When to do Deep Caching for this Delivery Service:

  • NEVER (default)
  • ALWAYS
displayName string The display name of the delivery service.
dnsBypassIp string The IPv4 IP to use for bypass on a DNS deliveryservice - bypass starts when serving more than the globalMaxMbps traffic on this deliveryservice.
dnsBypassIp6 string The IPv6 IP to use for bypass on a DNS deliveryservice - bypass starts when serving more than the globalMaxMbps traffic on this deliveryservice.
dnsBypassTtl string The TTL of the DNS bypass response.
dscp string The Differentiated Services Code Point (DSCP) with which to mark downstream (EDGE -> customer) traffic.
edgeHeaderRewrite string The EDGE header rewrite actions to perform.
geoLimitRedirectUrl string  
geoLimit string
  • 0: None - no limitations
  • 1: Only route on CZF file hit
  • 2: Only route on CZF hit or when from USA

Note that this does not prevent access to content or makes content secure; it just prevents routing to the content by Traffic Router.
geoLimitCountries string  
geoProvider string  
globalMaxMbps string The maximum global bandwidth allowed on this deliveryservice. If exceeded, the traffic routes to the dnsByPassIp* for DNS deliveryservices and to the httpBypassFqdn for HTTP deliveryservices.
globalMaxTps string The maximum global transactions per second allowed on this deliveryservice. When this is exceeded traffic will be sent to the dnsByPassIp* for DNS deliveryservices and to the httpBypassFqdn for HTTP deliveryservices
httpBypassFqdn string The HTTP destination to use for bypass on an HTTP deliveryservice - bypass starts when serving more than the globalMaxMbps traffic on this deliveryservice.
id string The deliveryservice id (database row number).
infoUrl string Use this to add a URL that points to more information about that deliveryservice.
initialDispersion string  
ipv6RoutingEnabled bool false: send IPv4 address of Traffic Router to client on HTTP type del.
lastUpdated string  
logsEnabled bool  
longDesc string Description field 1.
longDesc1 string Description field 2.
longDesc2 string Description field 2.
>>type string The type of MatchList (one of :ref:to-api-v11-types use_in_table=’regex’).
>>setNumber string The set Number of the matchList.
>>pattern string The regexp for the matchList.
maxDnsAnswers string The maximum number of IPs to put in a A/AAAA response for a DNS deliveryservice (0 means all available).
midHeaderRewrite string The MID header rewrite actions to perform.
missLat string The latitude to use when the client cannot be found in the CZF or the Geo lookup.
missLong string The longitude to use when the client cannot be found in the CZF or the Geo lookup.
multiSiteOrigin bool Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See Multi Site Origin
multiSiteOriginAlgor bool Is the Multi Site Origin feature enabled for this delivery service (0=false, 1=true). See Multi Site Origin
orgServerFqdn string The origin server base URL (FQDN when used in this instance, includes the protocol (http:// or https://) for use in retrieving content from the origin server.
originShield string  
profileDescription string The description of the Traffic Router Profile with which this deliveryservice is associated.
profileId string The id of the Traffic Router Profile with which this deliveryservice is associated.
profileName string The name of the Traffic Router Profile with which this deliveryservice is associated.
protocol string
qstringIgnore string
  • 0: no special query string handling; it is for use in the cache-key and pass up to origin.
  • 1: ignore query string in cache-key, but pass it up to parent and or origin.
  • 2: drop query string at edge, and do not use it in the cache-key.
rangeRequestHandling string

How to treat range requests:

  • 0 Do not cache (ranges requested from files taht are already cached due to a non range request will be a HIT)
  • 1 Use the background_fetch plugin.
  • 2 Use the cache_range_requests plugin.
regexRemap string Regex Remap rule to apply to this delivery service at the Edge tier.
regionalGeoBlocking bool Regex Remap rule to apply to this delivery service at the Edge tier.
remapText string Additional raw remap line text.
routingName string The routing name of this deliveryservice.
signed bool
  • false: token based auth (see :ref:token-based-auth) is not enabled for this deliveryservice.
  • true: token based auth is enabled for this deliveryservice.
sslKeyVersion string  
tenant string Owning tenant name
tenantId int Owning tenant ID.
trRequestHeaders string List of header keys separated by __RETURN__. Listed headers will be included in TR access log entries under the “rh=” token.
trResponseHeaders string List of header name:value pairs separated by __RETURN__. Listed pairs will be included in all TR HTTP responses.
type string The type of this deliveryservice (one of :ref:to-api-v11-types use_in_table=’deliveryservice’).
typeId string The type of this deliveryservice (one of :ref:to-api-v11-types use_in_table=’deliveryservice’).
xmlId string Unique string that describes this deliveryservice.

Response Example

{
  "response": [
    {
        "active": true,
        "cacheurl": null,
        "ccrDnsTtl": "3600",
        "cdnId": "2",
        "cdnName": "over-the-top",
        "checkPath": "",
        "deepCachingType": "NEVER",
        "displayName": "My Cool Delivery Service",
        "dnsBypassCname": "",
        "dnsBypassIp": "",
        "dnsBypassIp6": "",
        "dnsBypassTtl": "30",
        "dscp": "40",
        "edgeHeaderRewrite": null,
        "exampleURLs": [
            "http://foo.foo-ds.foo.bar.net"
        ],
        "geoLimit": "0",
        "geoLimitCountries": null,
        "geoLimitRedirectURL": null,
        "geoProvider": "0",
        "globalMaxMbps": null,
        "globalMaxTps": "0",
        "httpBypassFqdn": "",
        "id": "442",
        "infoUrl": "",
        "initialDispersion": "1",
        "ipv6RoutingEnabled": true,
        "lastUpdated": "2016-01-26 08:49:35",
        "logsEnabled": false,
        "longDesc": "",
        "longDesc1": "",
        "longDesc2": "",
        "matchList": [
            {
                "pattern": ".*\\.foo-ds\\..*",
                "setNumber": "0",
                "type": "HOST_REGEXP"
            }
        ],
        "maxDnsAnswers": "0",
        "midHeaderRewrite": null,
        "missLat": "41.881944",
        "missLong": "-87.627778",
        "multiSiteOrigin": false,
        "multiSiteOriginAlgorithm": null,
        "orgServerFqdn": "http://baz.boo.net",
        "originShield": null,
        "profileDescription": "Content Router for over-the-top",
        "profileId": "5",
        "profileName": "ROUTER_TOP",
        "protocol": "0",
        "qstringIgnore": "1",
        "rangeRequestHandling": "0",
        "regexRemap": null,
        "regionalGeoBlocking": false,
        "remapText": null,
        "routingName": "foo",
        "signed": false,
        "sslKeyVersion": "0",
        "tenant": "root",
        "tenantId": 1,
        "trRequestHeaders": null,
        "trResponseHeaders": "Access-Control-Allow-Origin: *",
        "type": "HTTP",
        "typeId": "8",
        "xmlId": "foo-ds"
    }
    { .. },
    { .. }
  ]
}

GET /api/1.2/user/current

Retrieves the profile for the authenticated user.

Authentication Required: Yes

Role(s) Required: None

Response Properties

Parameter Type Description
email string  
city string  
id string  
phoneNumber string  
company string  
country string  
fullName string  
localUser boolean  
uid string  
stateOrProvince string  
username string  
newUser boolean  
addressLine2 string  
role string  
addressLine1 string  
gid string  
postalCode string  
tenant string Owning tenant name
tenantId int Owning tenant ID

Response Example

{
       "response": {
                        "email": "email@email.com",
                        "city": "",
                        "id": "50",
                        "phoneNumber": "",
                        "company": "",
                        "country": "",
                        "fullName": "Tom Callahan",
                        "localUser": true,
                        "uid": "0",
                        "stateOrProvince": "",
                        "username": "tommyboy",
                        "newUser": false,
                        "addressLine2": "",
                        "role": "6",
                        "addressLine1": "",
                        "gid": "0",
                        "postalCode": "",
                        "tenant": "root",
                        "tenantId": 1

       },
}

PUT /api/1.2/user/current

Updates the date for the authenticated user.

Authentication Required: Yes

Role(s) Required: None

Request Properties

Parameter Type Description
email string  
city string  
id string  
phoneNumber string  
company string  
country string  
fullName string  
localUser boolean  
uid string  
stateOrProvince string  
username string  
newUser boolean  
addressLine2 string  
role string  
addressLine1 string  
gid string  
postalCode string  
tenantId int Owning tenant ID

Request Example

{
 "user": {
    "email": "",
    "city": "",
    "id": "",
    "phoneNumber": "",
    "company": "",
    "country": "",
    "fullName": "",
    "localUser": true,
    "uid": "0",
    "stateOrProvince": "",
    "username": "tommyboy",
    "newUser": false,
    "addressLine2": "",
    "role": "6",
    "addressLine1": "",
    "gid": "0",
    "postalCode": "",
    "tenant": "root",
    "tenantId": 1,

 }
}

Response Properties

Parameter Type Description
alerts array A collection of alert messages.
>level string Success, info, warning or error.
>text string Alert message.
version string  

Response Example

{
      "alerts": [
                {
                        "level": "success",
                        "text": "UserProfile was successfully updated."
                }
        ],
}

GET /api/1.2/user/current/jobs.json

Retrieves the user’s list of jobs.

Authentication Required: Yes

Role(s) Required: None

Request Query Parameters

Name Required Description
keyword no PURGE

Response Properties

Parameter Type Description
keyword string  
objectName string  
assetUrl string  
assetType string  
status string  
dsId string  
dsXmlId string  
username boolean  
parameters string  
enteredTime string  
objectType string  
agent string  
id string  
startTime string  
version string  

Response Example

{
 "response": [
    {
       "id": "1",
       "keyword": "PURGE",
       "objectName": null,
       "assetUrl": "",
       "assetType": "file",
       "status": "PENDING",
       "dsId": "9999",
       "dsXmlId": "ds-xml-id",
       "username": "peewee",
       "parameters": "TTL:56h",
       "enteredTime": "2015-01-21 18:00:16",
       "objectType": null,
       "agent": "",
       "startTime": "2015-01-21 10:45:38"
    }
 ],
}

POST/api/1.2/user/current/jobs

Invalidating content on the CDN is sometimes necessary when the origin was mis-configured and something is cached in the CDN that needs to be removed. Given the size of a typical Traffic Control CDN and the amount of content that can be cached in it, removing the content from all the caches may take a long time. To speed up content invalidation, Traffic Ops will not try to remove the content from the caches, but it makes the content inaccessible using the regex_revalidate ATS plugin. This forces a revalidation of the content, rather than a new get.

Note

This method forces a HTTP revalidation of the content, and not a new GET - the origin needs to support revalidation according to the HTTP/1.2 specification, and send a 200 OK or 304 Not Modified as applicable.

Authentication Required: Yes

Role(s) Required: None

Request Properties

Parameter Type Description
dsId string Unique Delivery Service ID
regex string Path Regex this should be a PCRE compatible regular expression for the path to match for forcing the revalidation. Be careful to only match on the content you need to remove - revalidation is an expensive operation for many origins, and a simple /.* can cause an overload condition of the origin.
startTime string Start Time is the time when the revalidation rule will be made active. Populate with the current time to schedule ASAP. This value cannot be more than 2 days before now.
ttl int Time To Live is how long the revalidation rule will be active for in hours. It usually makes sense to make this the same as the Cache-Control header from the origin which sets the object time to live in cache (by max-age or Expires). Entering a longer TTL here will make the caches do unnecessary work.

Request Example

{
       "dsId": "9999",
       "regex": "/path/to/content.jpg",
       "startTime": "2015-01-27 11:08:37",
       "ttl": 54
}

Response Properties

Parameter Type Description
alerts array A collection of alert messages.
>level string Success, info, warning or error.
>text string Alert message.
version string  

Response Example

{
      "alerts":
              [
                  {
                        "level": "success",
                        "text": "Successfully created purge job for: ."
                  }
              ],
}

POST /api/1.2/user/login

Authentication of a user using username and password. Traffic Ops will send back a session cookie.

Authentication Required: No

Role(s) Required: None

Request Properties

Parameter Type Description
u string username
p string password

Request Example

{
   "u": "username",
   "p": "password"
}

Response Properties

Parameter Type Description
alerts array A collection of alert messages.
>level string Success, info, warning or error.
>text string Alert message.
version string  

Response Example

{
  "alerts": [
     {
        "level": "success",
        "text": "Successfully logged in."
     }
  ],
 }

GET /api/1.2/user/:id/deliveryservices/available

Authentication Required: Yes

Role(s) Required: None

Request Route Parameters

Name Required Description
id yes  

Response Properties

Parameter Type Description
id string  
displayName string  
xmlId string  

Response Example

{
 "response": [
    {
       "id": "90",
       "displayName": "Foo Bar DS",
       "xmlId": "foo-bar"
    },
    {
       "id": "92",
       "displayName": "Foo Baz DS",
       "xmlId": "foo-baz"
    }
 ],
}

POST /api/1.2/user/login/token

Authentication of a user using a token.

Authentication Required: No

Role(s) Required: None

Request Properties

Parameter Type Description
t string token-value

Request Example

{
   "t": "token-value"
}

Response Properties

Parameter Type Description
alerts array  
>level string  
>text string  
version string  

Response Example

{
 "alerts": [
    {
       "level": "error",
       "text": "Unauthorized, please log in."
    }
 ],
}

POST /api/1.2/user/logout

User logout. Invalidates the session cookie.

Authentication Required: Yes

Role(s) Required: None

Response Properties

Parameter Type Description
alerts array  
  • level
 string  
  • text
 string  
version string  

Response Example

{
 "alerts": [
    {
       "level": "success",
       "text": "You are logged out."
    }
 ],
}

POST /api/1.2/user/reset_password

Reset user password.

Authentication Required: No

Role(s) Required: None

Request Properties

Parameter Type Description
email string The email address of the user to initiate password reset.

Request Example

{
 "email": "email@email.com"
}

Response Properties

Parameter Type Description
alerts array A collection of alert messages.
  • level
 string Success, info, warning or error.
  • text
 string Alert message.
version string  

Response Example

{
 "alerts": [
    {
       "level": "success",
       "text": "Successfully sent password reset to email 'email@email.com'"
    }
 ],
}