Users
Energy Asset - Users

Services relating to users of the Energy Asset Tool. “\

"NOTE: Use appropriate content-type header -- application/xml or application/json

Supported Formats

json, xml
>>>

GET /api/v2/users
Retrieve a list of users. NOTE: Users are only allowed to view their own account.This call always returns a 404.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
500 Unspecified error on server.
404 Listing all users is not supported.
>>>

POST /api/v2/users/authenticate
Authenticate user to get API token. Response for a successful request will be an object including a token to be used with future API requests.

Authenticate to the Energy Asset Score application to receive a token for use in future API requests. In order to authenticate a user account and organization token are also required. Contact asset.score@pnnl.gov to request an organization token. Use the organization token to create a user account. Follow the API documentation for user accounts: buildingenergyscore.energy.gov/apidoc/v2/users.html

Supported Formats

json, xml

Errors

Code Description
404 Unsupported operation
500 Unspecified error on server.
401 Request must contain username, password and organization token
401 Invalid email or password.
401 Invalid username, password or organization token

Examples

(json) POST https://buildingenergyscore.energy.gov/api/v2/users/authenticate?email=test@test.org&password=passw0rd&organization_token=1234TokenGoesHere
(json) Response:  {"user_id": 30, "token":"xzysuLdC2hiJfRGgMkAv"}

Params

Param name Description
email
required

Email address of the existing user

Validations:

  • Must be a String
password
required

Password for the existing account

Validations:

  • Must be a String
organization_token
required

Unique token required to generate a user token for future API calls.

Validations:

  • Must be a String
>>>

GET /api/v2/users/:id
Retrieve the user with the given ID. NOTE: Users are only allowed to view their own account.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
404 Unsupported operation
500 Unspecified error on server.

Examples

{"created_at":"2013-07-26T16:51:25Z","email":"user1@nowhere.com","id":12,"organization_token":"test0rg","role_id":1,"updated_at":"2013-07-26T16:51:25Z"}
<?xml version="1.0" encoding="UTF-8"?>
<user>
  <created-at type="datetime">2014-01-31T06:17:22Z</created-at>
  <email>user1@nowhere.com</email>
  <id type="integer">14</id>
  <organization-id type="integer">1</organization-id>
  <role-id type="integer">1</role-id>
  <updated-at type="datetime">2014-01-31T06:17:22Z</updated-at>
</user>
>>>

POST /api/v2/users
Create a new user account. Response for a successful request is a complete User object with the assigned unique ID of the new user.Password must contain uppercase, lowercase, digit and a special character.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
404 Unsupported operation
500 Unspecified error on server.

Examples

(json) POST {"first_name":"Somefirstname","last_name":"Somelastname","email":"test@test.org","password":"passw0rd","password_confirmation":"passw0rd","organization_token":"1234TokenGoesHere"}
(json) POST https://buildingenergyscore.energy.gov/api/v2/users?first_name=Somefirstname&last_name=Somelastname&email=test@test.org&password=passw0rd&password_confirmation=passw0rd&organization_token=1234TokenGoesHere
(json) Response: {"created_at":"2013-07-31T22:53:44Z","email":"newuser@nowhere.com","id":15,"organization_id":1,"role_id":1,"updated_at":"2013-07-31T22:53:44Z"}
(xml) POST https://buildingenergyscore.energy.gov/api/v2/users.xml?first_name=Somefirstname&last_name=Somelastname&email=test@test.org&password=passw0rd&password_confirmation=passw0rd&organization_token=1234TokenGoesHere
(xml) Response:
<user>
  <created-at type="datetime">2014-01-30T23:28:08Z</created-at>
  <email>test@test.org</email>
  <id type="integer">30</id>
  <organization-id type="integer">1</organization-id>
  <role-id type="integer">1</role-id>
  <updated-at type="datetime">2014-01-30T23:28:08Z</updated-at>
</user>

Params

Param name Description
organization_token
required

Unique organization token required to generate a user token for future API calls.

Validations:

  • Must be a String
email
required

Email address of the new user

Validations:

  • Must be a String
password
required

Password for the new user

Validations:

  • Must be a String
password_confirmation
required

Password again to ensure user didn't make a mistake

Validations:

  • Must be a String
first_name
required

First name.

Validations:

  • Must be a String
last_name
required

Last name.

Validations:

  • Must be a String
>>>

PUT /api/v2/users/:id
Update user account with given ID. Nothing is returned. NOTE: Users can only update their own account. Users NOT allowed to change role or organization.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
404 Unsupported operation
500 Unspecified error on server.
422 password and password_confirmation do NOT match

Examples

(json) Update email: PUT {"email": "test2@test.org"}
(xml) Update email and password:
<user>
  <email>test3@test.org</email>
  <password>testchange</password>
  <password_confirmation>testchange</password_confirmation>
</user>

Params

Param name Description
email
optional

Email address of the new user

Validations:

  • Must be a String
password
optional

Password for the new user

Validations:

  • Must be a String
password_confirmation
optional

Password again to ensure user didn't make a mistake

Validations:

  • Must be a String
first_name
optional

First name.

Validations:

  • Must be a String
last_name
optional

Last name.

Validations:

  • Must be a String