Users

Summary

The Users REST API provides user management to the API Manager's client registry.

Description

With the Users API, it is possible to create, delete, and manage users in the API Manager.

Resources

Resource	Since Version	Description
POST /api/portal/v1.3/users		Admin function to create a new user on the system
GET /api/portal/v1.3/users		Obtains a list of users
POST /api/portal/v1.3/users/forgotpassword		Allows a user to reset their password.
POST /api/portal/v1.3/users/register		Register a new user.
GET /api/portal/v1.3/users/resetpassword		Validates the user /forgotpassword password request.
GET /api/portal/v1.3/users/validateuser		Validates the user /register request.
GET /api/portal/v1.3/users/{id}		Retrieves the details for a given user.
PUT /api/portal/v1.3/users/{id}		Updates the details for a given user.
DELETE /api/portal/v1.3/users/{id}		Deletes a user.
POST /api/portal/v1.3/users/{id}/approve		Grants approval to a request to create a new user on the system.
POST /api/portal/v1.3/users/{id}/changepassword		Updates the password for a given user.
GET /api/portal/v1.3/users/{id}/image/		Get the image for a user
POST /api/portal/v1.3/users/{id}/image/		Set the image for a user
PUT /api/portal/v1.3/users/{id}/resetpassword		Admin level function to reset the password for a given user.

---

POST /api/portal/v1.3/users

Summary

Admin function to create a new user on the system

Description

Creates a new user on the system. Only Organization Administrators and API Manager Administrators may create users. Custom properties can be included on create.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
-	The API Manager user is a member of organizations.	User	body	Required

Status Codes

HTTP Status Code	Reason
201	Created
403	Forbidden
400	Bad Request
413	Request Entity Too Large
500	Internal Server Error

Returns Class

User

Example

POST https://localhost:8075/api/portal/v1.3/users

Request

{"organizationId":"6fb4bd38-199a-4e9f-8c11-43233f530d82","name":"New User","description":"Created by admin","email":"jbloggs@acmecorp.com","phone":"","mobile":null,"role":"user","image":null,"enabled":true}

Response
HTTP 1.1 201 Created

{
  "id" : "2be9fc6e-1110-474f-8029-bf1577ec3801",
  "organizationId" : "6fb4bd38-199a-4e9f-8c11-43233f530d82",
  "name" : "New User",
  "description" : "Created by admin",
  "loginName" : "jbloggs",
  "email" : "jbloggs@acmecorp.com",
  "phone" : "+353 (1) 6742000",
  "mobile" : "+353 (89) 6742087",
  "role" : "user",
  "image" : "resources/photo.jpg",
  "enabled" : true,
  "createdOn" : 1367337125476,
  "state" : "approved",
  "type" : "internal",
  "authAttrs" : null,
  "surname" : "User",
  "dn" : null
}

---

GET /api/portal/v1.3/users

Summary

Obtains a list of users

Description

Returns a list of users that are visible to the authenticated user. The list of users can be filtered using the expression: field=__field__&op=__op__&value=__value__. Optionally, you can add a logical operation for all expressions, using the form: &lop=AND|OR. By default, the logical operation is AND. Multiple expression filters can be used, specifying field, op, and value for each filter. The field is one of:

apiid

Matches the user if the user has explicit access to application(s) that are using the API, specified by ID

appid

Matches the user if the user has explicit access to the application, specified by ID

description

The user's description

email

The user's email address

enabled

The enabled state of the user, one of: enabled, disabled

createdOn

The date the user was created on, time in ms, e.g.: 1372755998542

mobile

The user's mobile phone

name

The name of the user

loginName

The login name of the user

orgid

Matches the user if the user is a member of the organization, specified by ID

phone

The user's phone

role

The user's role, one of: user or oadmin

state

The user's current state, one of: approved, pending

surname

The surname of the user

The op is an operation and is one of:

eq

Equal

ne

Not equal

gt

Greater than

lt

Less than

ge

Greater than or equal

le

Less than or equal

like

Like

gete

Greater than or equal to, and less than or equal to; the value should be a lower-minimum and upper-maximum separated by comma, e.g: value=5,10

The value will be compared against the field, according to the supplied op.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
field	Filter field name.	String	query		Multiple
op	Filter operation.	String	query		Multiple
value	Filter value	String / Integer	query		Multiple

Status Codes

HTTP Status Code	Reason
200	OK
400	Bad Request
500	Internal Server Error

Returns Array

[ User ]

Example

GET https://localhost:8075/api/portal/v1.3/users?field=name&op=eq&value=New User&field=role&op=eq&value=user

Response
HTTP 1.1 200 OK

[ {
  "id" : "2be9fc6e-1110-474f-8029-bf1577ec3801",
  "organizationId" : "6fb4bd38-199a-4e9f-8c11-43233f530d82",
  "name" : "New User",
  "description" : "Created by admin",
  "loginName" : "jbloggs",
  "email" : "jbloggs@acmecorp.com",
  "phone" : "+353 (1) 6742000",
  "mobile" : "+353 (89) 6742087",
  "role" : "user",
  "image" : "resources/photo.jpg",
  "enabled" : true,
  "createdOn" : 1367337125476,
  "state" : "approved",
  "type" : "internal",
  "authAttrs" : null,
  "surname" : "User",
  "dn" : null
} ]

---

POST /api/portal/v1.3/users/forgotpassword

Summary

Allows a user to reset their password.

Description

When this method is invoked, an email is sent to the owner of email to verify that they wish for their password to be reset. The owner of email must click on a link to reset the password. The link should direct the user to /resetpassword with appropriate query paremeters. Redirect URLs may be specified for success and failure conditions. If redirect URLs are specified, they must be a known Static File listener configured in the gateway or the request will be rejected.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
email	The email address of the user.	String	form	Required
success	The redirect success location (e.g. /request-forgotten-pw-success)	String	form
failure	The redirect failure location (e.g. /request-forgotten-pw-failed)	String	form

Status Codes

HTTP Status Code	Reason
201	Created
400	Bad Request
303	See Other

---

POST /api/portal/v1.3/users/register

Summary

Register a new user.

Description

Allows a user to register for an account on the system. A validation email request is sent to the provided email address to confirm ownership. The email should contain a link to /validateuser with appropriate parameters. User properties (including custom properties) may be supplied as form parameters. The method will return JSON, but optionally, redirect URLs may be specified for success and failure conditions. If redirect URLs are specified, they must be a known Static File listener configured in the gateway or the request will be rejected.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
name	The name of the user to register.	String	form	Required
email	The unique email address of the user to register.	String	form	Required
password	The password of the user to register.	String	form	Required
token	The registration token to use.	String	form
success	The redirect success location (e.g. '/registration-success')	String	form
failure	The redirect failure location (e.g. '/registration-failed')	String	form

Status Codes

HTTP Status Code	Reason
201	Created
400	Bad Request
303	See Other

---

GET /api/portal/v1.3/users/resetpassword

Summary

Validates the user /forgotpassword password request.

Description

User validation code and email address are expected as query string parameters. When invoked, an email will be sent to the user with their new password.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
email	The email address of the user being validated.	String	query	Required
validator	Validation string for the user entry.	String	query	Required

Status Codes

HTTP Status Code	Reason
303	See Other
404	Not Found

---

GET /api/portal/v1.3/users/validateuser

Summary

Validates the user /register request.

Description

User validation code and email address are expected as query parameters.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
email	The email address of the user being validated.	String	query	Required
validator	Validation string for the user entry.	String	query	Required

Status Codes

HTTP Status Code	Reason
303	See Other
400	Bad Request

---

GET /api/portal/v1.3/users/{id}

Summary

Retrieves the details for a given user.

Description

Retrieves user details, given a user ID. The API Manager Administrator may access all users, otherwise, the user ID must be a member of the authenticated user's own organization.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
id	The ID of the user to be retreived.	String	path	Required

Status Codes

HTTP Status Code	Reason
200	OK
404	Not Found

Returns Class

User

Example

GET https://localhost:8075/api/portal/v1.3/users/{id}

Request

{"id":"2be9fc6e-1110-474f-8029-bf1577ec3801","organizationId":"6fb4bd38-199a-4e9f-8c11-43233f530d82","name":"New User","description":"Created by admin","email":"jbloggs@acmecorp.com","phone":"","mobile":null,"role":"user","image":null,"enabled":true,"createdOn":1364485056615,"state":"approved"}

Response
HTTP 1.1 200 OK

{
  "id" : "2be9fc6e-1110-474f-8029-bf1577ec3801",
  "organizationId" : "6fb4bd38-199a-4e9f-8c11-43233f530d82",
  "name" : "New User",
  "description" : "Created by admin",
  "loginName" : "jbloggs",
  "email" : "jbloggs@acmecorp.com",
  "phone" : "+353 (1) 6742000",
  "mobile" : "+353 (89) 6742087",
  "role" : "user",
  "image" : "resources/photo.jpg",
  "enabled" : true,
  "createdOn" : 1367337125476,
  "state" : "approved",
  "type" : "internal",
  "authAttrs" : null,
  "surname" : "User",
  "dn" : null
}

---

PUT /api/portal/v1.3/users/{id}

Summary

Updates the details for a given user.

Description

Updates user details, given a user ID. The API Manager Administrator may update all users, otherwise, the user ID must be a member of the authenticated user's own organization and the authenticated user must be an Organization Administrator.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
id	The ID of the user being updated.	String	path	Required
-	The API Manager user is a member of organizations.	User	body	Required

Status Codes

HTTP Status Code	Reason
200	OK
401	Unauthorized
500	Internal Server Error
404	Not Found

Returns Class

User

Example

PUT https://localhost:8075/api/portal/v1.3/users/{id}

Request

{"id":"2be9fc6e-1110-474f-8029-bf1577ec3801","organizationId":"6fb4bd38-199a-4e9f-8c11-43233f530d82","name":"New User","description":"Created by admin","email":"jbloggs@acmecorp.com","phone":"","mobile":null,"role":"user","image":null,"enabled":true,"createdOn":1364485056615,"state":"approved"}

Response
HTTP 1.1 200 OK

{
  "id" : "2be9fc6e-1110-474f-8029-bf1577ec3801",
  "organizationId" : "6fb4bd38-199a-4e9f-8c11-43233f530d82",
  "name" : "New User",
  "description" : "Created by admin",
  "loginName" : "jbloggs",
  "email" : "jbloggs@acmecorp.com",
  "phone" : "+353 (1) 6742000",
  "mobile" : "+353 (89) 6742087",
  "role" : "user",
  "image" : "resources/photo.jpg",
  "enabled" : true,
  "createdOn" : 1367337125476,
  "state" : "approved",
  "type" : "internal",
  "authAttrs" : null,
  "surname" : "User",
  "dn" : null
}

---

DELETE /api/portal/v1.3/users/{id}

Summary

Deletes a user.

Description

Deletes a user and deletes all their associated application(s) and key(s).The authenticated user must be API Manager Administrator or an Organization Administrator of the user's organization with the correct privileges to invoke this method.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
id	The user ID to delete	String	path	Required

Status Codes

HTTP Status Code	Reason
204	No Content

---

POST /api/portal/v1.3/users/{id}/approve

Summary

Grants approval to a request to create a new user on the system.

Description

Approving user must be API Manager Administrator or an Organization Administrator of the user's organization with the correct privileges to approve new user requests.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
id	The ID of the user to be approved.	String	path	Required

Status Codes

HTTP Status Code	Reason
201	Created
403	Forbidden
404	Not Found
500	Internal Server Error

Returns Class

User

Example

POST https://localhost:8075/api/portal/v1.3/users/{id}/approve

Response
HTTP 1.1 201 Created

{
  "id" : "2be9fc6e-1110-474f-8029-bf1577ec3801",
  "organizationId" : "6fb4bd38-199a-4e9f-8c11-43233f530d82",
  "name" : "New User",
  "description" : "Created by admin",
  "email" : "jbloggs@acmecorp.com",
  "phone" : "",
  "mobile" : null,
  "role" : "user",
  "image" : null,
  "enabled" : true,
  "createdOn" : 1364485056615,
  "state" : "approved"
}

---

POST /api/portal/v1.3/users/{id}/changepassword

Summary

Updates the password for a given user.

Description

The authenticated user must be API Manager Administrator or an Organization Administrator of the user's organization with the correct privileges to invoke this method.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
id	The ID of the user being updated.	String	path	Required
newPassword	The new password of the user being updated.	String	form	Required

Status Codes

HTTP Status Code	Reason
204	No Content
401	Unauthorized
404	Not Found
400	Bad Request

---

GET /api/portal/v1.3/users/{id}/image/

Summary

Get the image for a user

Description

Returns the jpeg image associated with an user.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
id	The user ID whos image is to be returned	String	path	Required

Status Codes

HTTP Status Code	Reason
204	No Content
404	Not Found
500	Internal Server Error

---

POST /api/portal/v1.3/users/{id}/image/

Summary

Set the image for a user

Description

Set the jpeg image to be associated with a user.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
id	The user ID for which an image is to be updated	String	path	Required
file	The file input data	File	form	Required
type	This value should be unset	String	query	Required

Status Codes

HTTP Status Code	Reason
204	No Content
400	Bad Request
413	Request Entity Too Large
500	Internal Server Error

---

PUT /api/portal/v1.3/users/{id}/resetpassword

Summary

Admin level function to reset the password for a given user.

Description

The authenticated user must be API Manager Administrator or an Organization Administrator of the user's organization with the correct privileges to invoke this method.

Parameters

Parameter	Description	Data Type	Location	Required	Multiple
id	The ID of the user having password reset administratively.	String	path	Required

Status Codes

HTTP Status Code	Reason
200	OK
401	Unauthorized
500	Internal Server Error
404	Not Found
400	Bad Request

Returns Class

User

---