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 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 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 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 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 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 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 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 (bymax-age
orExpires
). 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 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'" } ], }