users
GET
Retrieves all requested users.
- Auth. Required
Yes
- Roles Required
None1
- Permissions Required
USER:READ
- Response Type
Array
Request Structure
Name |
Required |
Description |
---|---|---|
id |
no |
Return only the user identified by this integral, unique identifier |
tenant |
no |
Return only users belonging to the Tenant identified by tenant name |
role |
no |
Return only users belonging to the Role identified by role name |
username |
no |
Return only the user with this username |
orderby |
no |
Choose the ordering of the results - must be the name of one of the fields of the
objects in the |
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 |
GET /api/5.0/users?username=mike HTTP/1.1
User-Agent: python-requests/2.25.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
Response Structure
- addressLine1
The user’s address - including street name and number
- addressLine2
An additional address field for e.g. apartment number
- changeLogCount
The number of change log entries created by the user
- city
The name of the city wherein the user resides
- company
The name of the company for which the user works
- country
The name of the country wherein the user resides
The user’s email address
- fullName
The user’s full name, e.g. “John Quincy Adams”
- gid
A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user - now it is always
null
Deprecated since version 4.0: This field is serves no known purpose, and shouldn’t be used for anything so it can be removed in the future.
- id
An integral, unique identifier for this user
- lastAuthenticated
The date and time at which the user was last authenticated, in RFC 3339
- lastUpdated
The date and time at which the user was last modified, in Traffic Ops’s Custom Date/Time Format
- newUser
A meta field with no apparent purpose that is usually
null
unless explicitly set during creation or modification of a user via some API endpoint- phoneNumber
The user’s phone number
- postalCode
The postal code of the area in which the user resides
- publicSshKey
The user’s public key used for the SSH protocol
- registrationSent
If the user was created using the users/register endpoint, this will be the date and time at which the registration email was sent - otherwise it will be
null
- role
The name of the role assigned to this user
- stateOrProvince
The name of the state or province where this user resides
- tenant
The name of the tenant to which this user belongs
- tenantId
The integral, unique identifier of the tenant to which this user belongs
- ucdn
The name of the uCDN to which the user belongs
- uid
A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user - now it is always
null
Deprecated since version 4.0: This field is serves no known purpose, and shouldn’t be used for anything so it can be removed in the future.
- username
The user’s username
HTTP/1.1 200 OK
Content-Encoding: gzip
Content-Type: application/json
Permissions-Policy: interest-cohort=()
Set-Cookie: mojolicious=...; Path=/; Expires=Fri, 13 May 2022 23:16:14 GMT; Max-Age=3600; HttpOnly
Vary: Accept-Encoding
X-Server-Name: traffic_ops_golang/
Date: Fri, 13 May 2022 22:16:14 GMT
Content-Length: 350
{ "response": [
{
"addressLine1": "22 Mike Wazowski You've Got Your Life Back Lane",
"addressLine2": null,
"changeLogCount": 0,
"city": "Monstropolis",
"company": null,
"country": null,
"email": "mwazowski@minc.biz",
"fullName": "Mike Wazowski",
"gid": null,
"id": 3,
"lastAuthenticated": null,
"lastUpdated": "2022-05-13T22:13:54.605052Z",
"newUser": true,
"phoneNumber": null,
"postalCode": null,
"publicSshKey": null,
"registrationSent": null,
"role": "admin",
"stateOrProvince": null,
"tenant": "root",
"tenantId": 1,
"ucdn": "",
"uid": null,
"username": "mike"
}
]}
POST
Creates a new user.
- Auth. Required
Yes
- Roles Required
“admin” or “operations”1
- Permissions Required
USER:CREATE, USER:READ
- Response Type
Object
Request Structure
- addressLine1
An optional field which should contain the user’s address - including street name and number
- addressLine2
An optional field which should contain an additional address field for e.g. apartment number
- city
An optional field which should contain the name of the city wherein the user resides
- company
An optional field which should contain the name of the company for which the user works
- country
An optional field which should contain the name of the country wherein the user resides
The user’s email address The given email is validated (circuitously) by GitHub user asaskevich’s regular expression . Note that it can’t actually distinguish a valid, deliverable, email address but merely ensure the email is in a commonly-found format.
- fullName
The user’s full name, e.g. “John Quincy Adams”
- gid
A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user
Deprecated since version 4.0: This field is serves no known purpose, and shouldn’t be used for anything so it can be removed in the future.
- localPasswd
The user’s password
- newUser
An optional meta field with no apparent purpose - don’t use this
- phoneNumber
An optional field which should contain the user’s phone number
- postalCode
An optional field which should contain the user’s postal code
- publicSshKey
An optional field which should contain the user’s public encryption key used for the SSH protocol
- role
The name that corresponds to the highest permission role which will be permitted to the user
- stateOrProvince
An optional field which should contain the name of the state or province in which the user resides
- tenantId
The integral, unique identifier of the tenant to which the new user shall belong
- ucdn
The name of the uCDN to which the user belongs
- uid
A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user
Deprecated since version 4.0: This field is serves no known purpose, and shouldn’t be used for anything so it can be removed in the future.
- username
The new user’s username
POST /api/5.0/users HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: curl/7.47.0
Accept: */*
Cookie: mojolicious=...
Content-Length: 304
Content-Type: application/json
{
"username": "mike",
"addressLine1": "22 Mike Wazowski You've Got Your Life Back Lane",
"city": "Monstropolis",
"compary": "Monsters Inc.",
"email": "mwazowski@minc.biz",
"fullName": "Mike Wazowski",
"localPasswd": "BFFsully",
"confirmLocalPasswd": "BFFsully",
"newUser": true,
"role": "admin",
"tenantId": 1
}
Response Structure
- addressLine1
The user’s address - including street name and number
- addressLine2
An additional address field for e.g. apartment number
- changeLogCount
The number of change log entries created by the user
- city
The name of the city wherein the user resides
- company
The name of the company for which the user works
- country
The name of the country wherein the user resides
The user’s email address
- fullName
The user’s full name, e.g. “John Quincy Adams”
- gid
A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX group ID of the user - now it is always
null
Deprecated since version 4.0: This field is serves no known purpose, and shouldn’t be used for anything so it can be removed in the future.
- id
An integral, unique identifier for this user
- lastAuthenticated
The date and time at which the user was last authenticated, in RFC 3339
- lastUpdated
The date and time at which the user was last modified, in Traffic Ops’s Custom Date/Time Format
- newUser
A meta field with no apparent purpose that is usually
null
unless explicitly set during creation or modification of a user via some API endpoint- phoneNumber
The user’s phone number
- postalCode
The postal code of the area in which the user resides
- publicSshKey
The user’s public key used for the SSH protocol
- registrationSent
If the user was created using the users/register endpoint, this will be the date and time at which the registration email was sent - otherwise it will be
null
- role
The name of the role assigned to this user
- stateOrProvince
The name of the state or province where this user resides
- tenant
The name of the tenant to which this user belongs
- tenantId
The integral, unique identifier of the tenant to which this user belongs
- ucdn
The name of the uCDN to which the user belongs
- uid
A deprecated field only kept for legacy compatibility reasons that used to contain the UNIX user ID of the user - now it is always
null
Deprecated since version 4.0: This field is serves no known purpose, and shouldn’t be used for anything so it can be removed in the future.
- username
The user’s username
HTTP/1.1 201 Created
Content-Encoding: gzip
Content-Type: application/json
Location: /api/5.0/users?id=3
Permissions-Policy: interest-cohort=()
Set-Cookie: mojolicious=...; Path=/; Expires=Fri, 13 May 2022 23:13:54 GMT; Max-Age=3600; HttpOnly
Vary: Accept-Encoding
X-Server-Name: traffic_ops_golang/
Date: Fri, 13 May 2022 22:13:54 GMT
Content-Length: 382
{ "alerts": [
{
"text": "user was created.",
"level": "success"
}
],
"response": {
"addressLine1": "22 Mike Wazowski You've Got Your Life Back Lane",
"addressLine2": null,
"changeLogCount": null,
"city": "Monstropolis",
"company": null,
"country": null,
"email": "mwazowski@minc.biz",
"fullName": "Mike Wazowski",
"gid": null,
"id": 3,
"lastAuthenticated": null,
"lastUpdated": "2022-05-13T22:13:54.605052Z",
"newUser": true,
"phoneNumber": null,
"postalCode": null,
"publicSshKey": null,
"registrationSent": null,
"role": "admin",
"stateOrProvince": null,
"tenant": "root",
"tenantId": 1,
"ucdn": "",
"uid": null,
"username": "mike"
}}