Skip to content

user_management.md

Latest commit

 

History

History
executable file
·
845 lines (634 loc) · 14.2 KB

user_management.md

File metadata and controls

executable file
·
845 lines (634 loc) · 14.2 KB
Raw

User Management endpoints

This set of endpoints is for managing users in the new CloudTrax user system.

functionality method endpoint
Edit a user PUT /user/<id>
Disable a user PUT /user/<id>/disable
Enable a user PUT /user/<id>/enable
Delete a user DELETE /user/<id>
Get a user GET /user/<id>
Create a user API key POST /user/<id>/key
Create a user API key POST /user/key
List user API keys GET /user/<id>/key/list
Delete a user API key DELETE /user/<id>/key/<id>
Delete a user API key DELETE /user/key/<id>
Create a user POST /user
List users GET /user/list
Edit a user password PUT /user/<id>/password
Create a user password reset token POST /user/<id>/password_set
Get a user network permission GET /user/<id>/network/<id>
Get a user account permission GET /user/<id>/account
Get a user service agreement status GET /user/<id>/service_agreement
Edit a user service agreement status PUT /user/<id>/service_agreement
Create a permission for a user on a network PUT /network/<id>/user/<id>
Delete a permission for a user on a network DELETE /network/<id>/user/<id>
Create a permission for a user on a network group PUT /networkgroup/<id>/user/<id>
Delete a permission for a user on a network group DELETE /networkgroup/<id>/user/<id>

Edit a user

PUT /user/<id>

Edit details about a user.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions

N/A

Example request
PUT https://api-v2.cloudtrax.com/user/123

{
	"name":"foo",
	"notes":"district manager. watch out for him."
}
Example response
{
}

Error codes

30002 20000 20038

Disable a user

PUT /user/<id>/disable

Disable a user. User will not be able to login or make any requests to the API after this endpoint has been successfully called. User information and permissions will be retained, but API keys will be removed.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions

N/A

Example request
PUT https://api-v2.cloudtrax.com/user/123/disable
Example response
{
}

Error codes

30002 20038 20029

Enable a user

PUT /user/<id>/enable

Enable a user. User will be able to login and make requests to the API after this endpoint has been successfully called. User information and permissions will be restored, but new API keys will have to be generated.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions

N/A

Example request
PUT https://api-v2.cloudtrax.com/user/123/enable
Example response
{
}

Error codes

30002 20038 20029

Delete a user

DELETE /user/<id>

Delete a user. All user information (including permissions and API keys) will be permanently removed.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions

N/A

Example request
DELETE https://api-v2.cloudtrax.com/user/123
Example response
{
}

Error codes

30002 20004 20038 20029

Get a user

GET /user/<id>

Get a user's information. This is information that is likely only of interest to Account Admins and Group Managers and not Network Users. For example, "notes" about a user may not be something administrators want to share. Or, "permissions" are only relevant to administrators, because a Network User cannot change their own.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions

N/A

Example request
GET https://api-v2.cloudtrax.com/user/123
Example response
{
	"email":"foo@bar.com",
	"name":"foo",
	"notes":"he is a bar",
	"role_id":2, /* account role ID */
	"account_id":123,
	"enabled":true,
	"verified":true,
	"permissions":{
		/* networks that were assigned explicitly and via network groups */
		"all_networks":[
			{"network_id":1, "role_id":3},
			{"network_id":2, "role_id":3},
			{"network_id":3, "role_id":3}
		],
		/* only specifically assigned networks */
		"assigned_networks":[
			{"network_id":3, "role_id":3}
		],
		/* only specifically assigned network groups */
		"assigned_networkgroups":[
			{"networkgroup_id":1, "role_id":3} /* contains network IDs 1 and 2 */
		],
	}
}

Error codes

30002 20004 20038

Create a user API key

POST /user/<id>/key POST /user/key

Create an API key for the specified user or the user making the request (if the <id> is not specified). API keys have identical API permissions to a logged in user, but do not require entering the user's email and password. They should still be kept secret, even though the user's password is never accessible.

Limit 10 keys generated via this endpoint per user at once.

The "key" property must be stored after creation, because it is stored securely and cannot be retrieved again.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User X
Resource Permissions

N/A

Example request
POST https://api-v2.cloudtrax.com/user/123/key
POST https://api-v2.cloudtrax.com/user/key
Example response
{
	"user_key_id":123,
	"key":"abc",
	"secret":"def",
	"created":"1970-01-01T00:00:00Z"
}

Error codes

30002 20004 20038 20044

List user API keys

GET /user/<id>/key/list

Get a list of API keys for the specified user that were generated via the Create user API key endpoint.

The "key" is not returned, because it is stored securely. If you lose the "key", you must generated a new API key.

Account Permissions
Role Permitted
Account Admin X
Group Manager
Network User
Resource Permissions

N/A

Example request
GET https://api-v2.cloudtrax.com/user/123/key/list
Example response
{
	"keys":[
		{
			"user_key_id":123,
			"secret":"def",
			"created":"1970-01-01T00:00:00Z"
		}
	]
}

Error codes

30002 20004 20038

Delete a user API key

DELETE /user/<id>/key/<id> DELETE /user/key/<id>

Delete an API key (generated via the Create user API key endpoint) for the specified user or the user making the request (if the <id> following /user/ is not specified).

Account Permissions
Role Permitted
Account Admin X
Group Manager
Network User
Resource Permissions

N/A

Example request
DELETE https://api-v2.cloudtrax.com/user/123/key/456
DELETE https://api-v2.cloudtrax.com/user/key/456
Example response
{
}

Error codes

30002 20004 20038 20043

Create a user

POST /user

Create a user in the same account as the requester.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions

N/A

Example request
POST https://api-v2.cloudtrax.com/user

{
	"email":"foo@bar.com",
	"name":"foo",
	"role_id":1, /* account role ID */
	"notes":"foo needs bar"
}
Example response
{
	"user_id":2,
	"account_id":123,
	"token":"abc", /* used to verify the user */
	"email":"foo@bar.com",
	"name":"foo",
	"role_id":1 /* account role ID */
}

Error codes

30002 20000 20010 20012 20014 20015 20029 20036

List users

GET /user/list

Get a list of users on the requester's account.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions

N/A

Example request
GET https://api-v2.cloudtrax.com/user/list
Example response
{
	"users":[
		{
			"user_id":2,
			"email":"fizz@buzz.com",
			"name":"fizz",
			"verified":true,
			"enabled":true,
			"notes":"fizzbuzz",
			"role_id":7,
			"created":"2017-06-08T00:00:00Z",
			"highest_network_role_id":4 /* only applicable to users with assigned roles, i.e., not Account Admins */
		}
	]
}

Error codes

30002

Edit a user password

PUT /user/<id>/password

Update the requester's password.

Account Permissions

Only the requester may access this endpoint.

Resource Permissions

N/A

Example request
PUT https://api-v2.cloudtrax.com/user/123/password

{
	"password_current":"L33T",
	"password_new":"$P34K"
}
Example response
{
}

Error codes

20003 20004 20029 20030 20038 20045

Create a user password reset token

POST /user/<id>/password_set

Create a token for resetting a password. This is meant for administrators to be able to reset a user's password without having to see the password; rather they can just deliver the token to the user and have the user set their own password.

Limit 10 tokens per user at once.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions

N/A

Example request
POST https://api-v2.cloudtrax.com/user/123/password_set
Example response
{
	"user_id":2,
	"token":"abc"
}

Error codes

30002 20004 20029 20033 20038 20045

Get a user network permission

GET /user/<id>/network/<id>

Get the role ID for the given network for the requester.

Account Permissions

Only the requester may access this endpoint.

Resource Permissions

N/A

Example request
GET https://api-v2.cloudtrax.com/user/123/network/456
Example response
{
	"role_id":4
}

Error codes

12047 20029

Get a user account permission

GET /user/<id>/account

Get the account role ID for the given network for the requester.

Account Permissions

Only the requester may access this endpoint.

Resource Permissions

N/A

Example request
GET https://api-v2.cloudtrax.com/user/123/account
Example response
{
	"account_id":1,
	"role_id":2
}

Error codes

30002 20004 20038 20043

Get a user service agreement status

GET /user/<id>/service_agreement

Get the status of the requester's acceptance of the service agreement.

Account Permissions

Only the requester may access this endpoint.

Resource Permissions

N/A

Example request
GET https://api-v2.cloudtrax.com/user/123/service_agreement
Example response
{
	"valid":true
}

Error codes

20029

Edit a user service agreement status

PUT /user/<id>/service_agreement

Accept the service agreement for the requester.

Account Permissions

Only the requester may access this endpoint.

Resource Permissions

N/A

Example request
PUT https://api-v2.cloudtrax.com/user/123/service_agreement
Example response
{
}

Error codes

20029

Create a permission for a user on a network

PUT /network/<id>/user/<id>

Create a permission for the specified user on the specified network.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions
Role Permitted
Network Editor X
Network Viewer
Voucher Editor
Example request
PUT https://api-v2.cloudtrax.com/network/1/user/123

{
	"role_id":4
}
Example response
{
}

Error codes

12047 20000 20016 20018 20027

Delete a permission for a user on a network

DELETE /network/<id>/user/<id>

Delete the specified user's permission the specified network.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions
Role Permitted
Network Editor X
Network Viewer
Voucher Editor
Example request
DELETE https://api-v2.cloudtrax.com/network/1/user/123
Example response
{
}

Error codes

30002 20019 20020 40006

Create a permission for a user on a network group

PUT /networkgroup/<id>/user/<id>

Create a permission for the specified user on the specified network group.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions
Role Permitted
Network Editor X
Network Viewer
Voucher Editor
Example request
PUT https://api-v2.cloudtrax.com/networkgroup/1/user/123

{
	"role_id":4
}
Example response
{
}

Error codes

30002 20000 20016 20017 20027 40006

Delete a permission for a user on a network group

DELETE /networkgroup/<id>/user/<id>

Delete the specified user's permission the specified network group.

Account Permissions
Role Permitted
Account Admin X
Group Manager X
Network User
Resource Permissions
Role Permitted
Network Editor X
Network Viewer
Voucher Editor
Example request
DELETE https://api-v2.cloudtrax.com/networkgroup/1/user/123
Example response
{
}

Error codes

30002 20019 20020 40006