Users¶

Table of Contents

Resource description
- Attributes
- Relationships
List Users
Create a User
Retrieve a User
Update a User
Deactivate a User

Resource description ¶

All endpoints adhere to the JSON API specification.

Attributes ¶

User Attributes¶
Name	Description	Required?	Type	Notes
appaId	The user’s APPA ID as a UUID	No	String	Automatically generated when user is created
assetRole	The user’s role in Asset Tracker	No	Integer or null	Spectator (0), Member (1), Leader (2), Admin (3), or null
email	The user’s email address	Yes	String	Unique
estIsEmailSubscriber	Receive email communications related to Safety Tracker?	No	Boolean	Default is `false`.
estIsPointOfContact	Is the user a Point of Contact for Safety Tracker?	No	Boolean	Default is `false`.
estRole	The user’s Safety Tracker role	Yes	Integer or null	Spectator (0), Member (1), Leader (2), Admin (3), or null
isEmailSubscriber	Receive email communications related to Reliability Tracker?	No	Boolean	Default is `false`.
isPointOfContact	Is the user a Point of Contact for Reliability Tracker?	No	Boolean	Default is `false`.
password	The user’s password	No	String	Required only on create. Maximum 32 characters.
requiresPasswordReset	Prompt the user to change their password on their next login?	No	Boolean	Default is `false`.
role	The user’s Reliability Tracker role.	Yes	Integer or null	Spectator (0), Member (1), Leader (2), Admin (3), or null
timezoneOffset	The user’s timezone offset from UTC	No	Decimal	Between `-12.0` and `12.0`. Default is `0`.
username	The user’s username	Yes	String	Unique. Maximum 254 characters.

Relationships ¶

User Relationships¶
Name	Description	Required?	Type
Memberships	Associates Users to Utilities	True	Foreign key
Outages	Associates a User to an Outage	True	Foreign key

List Users ¶

A user must have “spectator” authorization to list Users.

GET https://reliability.api.publicpower.org/v1/users/¶

Example request:

GET /v1/users/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Query Parameters

page (int) – Page Number of results to request.
page_size (int) – Number of results to return per-page.
sort (string) – Comma separated attribute names used to sort list. Available options: All User Attributes. To specify reverse ordering, prepend the attribute with -. Example: ordering=username,-role
filter[appa_id] (string) – Limit results to the given APPA ID as a UUID.
filter[username] (string) – Limit results to the given Username.
filter[utilities] (int) – Limit results to a comma-separated list of Utility IDs.

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "links": {
    "first": "https://reliability.api.publicpower.org/v1/users/?page=1",
    "last": "https://reliability.api.publicpower.org/v1/users/?page=1",
    "next": null,
    "prev": null
  },
  "data": [
    {
      "type": "User",
      "id": "1213",
      "attributes": {
        "appaId": "19047486-ae23-4f0d-919d-9b2a450e7ba4",
        "assetRole": null,
        "email": "web@stevepiercy.com",
        "estIsEmailSubscriber": false,
        "estIsPointOfContact": false,
        "estRole": 3,
        "isEmailSubscriber": false,
        "isPointOfContact": false,
        "requiresPasswordReset": false,
        "role": 3,
        "timezoneOffset": 0.0,
        "username": "stevepiercy"
      },
      "relationships": {
        "memberships": {
          "meta": {
            "count": 1
          },
          "data": [
            {
              "type": "Membership",
              "id": "1462"
            }
          ]
        },
        "utilities": {
          "meta": {
            "count": 1
          },
          "data": [
            {
              "type": "Utility",
              "id": "177"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pages": 1,
      "count": 1
    }
  }
}

Status Codes

200 OK – Successful response
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.

Create a User ¶

A user must have “admin” or “leader” authorization to create Users.

However when creating a user for a given service, the creator must have an “admin” or “leader” role in that service.

For example, Alex has the “admin” role only for eReliability Tracker. Alex can create users for a Utility in eReliability Tracker, but not in eSafety Tracker.

POST https://reliability.api.publicpower.org/v1/users/¶

Example request:

POST /v1/users/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

{
  "data": {
    "type": "User",
    "attributes": {
      "email": "deleteme@testing.com",
      "estIsEmailSubscriber": true,
      "estIsPointOfContact": true,
      "role": null,
      "estRole": 0,
      "isEmailSubscriber": true,
      "password": "deleteme9999",
      "timezoneOffset": "-8.0",
      "username": "deleteme999"},
    "relationships": {
      "utilities": {
        "data": [{
          "type": "Utility",
            "id": "177"}]
      }
    }
  }
}

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Example response:

HTTP/1.1 201 Created
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "User",
    "id": "2939",
    "attributes": {
      "appaId": "a82982b0-d027-4843-97ff-358b68ec9943",
      "assetRole": null,
      "email": "deleteme@testing.com",
      "estIsEmailSubscriber": true,
      "estIsPointOfContact": true,
      "estRole": 0,
      "isEmailSubscriber": true,
      "isPointOfContact": false,
      "requiresPasswordReset": false,
      "role": null,
      "timezoneOffset": -8.0,
      "username": "deleteme999"
    },
    "relationships": {
      "memberships": {
        "meta": {
          "count": 1
        },
        "data": [
          {
            "type": "Membership",
            "id": "4203"
          }
        ]
      },
      "utilities": {
        "meta": {
          "count": 1
        },
        "data": [
          {
            "type": "Utility",
            "id": "177"
          }
        ]
      }
    }
  }
}

Status Codes

201 Created – User created
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.

Retrieve a User ¶

A user must have “leader” authorization to retrieve any User. Any user may get their own user record with a valid access token.

GET https://reliability.api.publicpower.org/v1/users/(int: user_id)/¶

Example request:

GET /v1/users/1213/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "User",
    "id": "1213",
    "attributes": {
      "appaId": "19047486-ae23-4f0d-919d-9b2a450e7ba4",
      "assetRole": null,
      "email": "web@stevepiercy.com",
      "estIsEmailSubscriber": false,
      "estIsPointOfContact": false,
      "estRole": 3,
      "isEmailSubscriber": false,
      "isPointOfContact": false,
      "requiresPasswordReset": false,
      "role": 3,
      "timezoneOffset": 0.0,
      "username": "stevepiercy"
    },
    "relationships": {
      "memberships": {
        "meta": {
          "count": 1
        },
        "data": [
          {
            "type": "Membership",
            "id": "1462"
          }
        ]
      },
      "utilities": {
        "meta": {
          "count": 1
        },
        "data": [
          {
            "type": "Utility",
            "id": "177"
          }
        ]
      }
    }
  }
}

Status Codes

200 OK – Successful response
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.

Update a User ¶

A user must have “admin” authorization to update all User attributes.

However when updating a user for a given service, the updater must have an “admin” or “leader” role in that service.

For example, Alex has the “admin” role only for eReliability Tracker. Alex can update users for a Utility in eReliability Tracker, but not in eSafety Tracker.

A user authorized as a Utility’s “leader” can update attributes for users for their Utility in the following list.

assetRole
email
estIsEmailSubscriber
estIsPointOfContact
estRole
isEmailSubscriber
password
role
timezoneOffset
username
utilities

A user who is neither a Leader nor Admin may update their own attributes in the following list.

email
estIsEmailSubscriber
isEmailSubscriber
password
timezoneOffset
username

PATCH https://reliability.api.publicpower.org/v1/users/(int: user_id)/¶

Example request:

PATCH /v1/users/2861/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

{
  "data": {
    "attributes": {
      "email": "deleteme@testing.com",
      "estIsEmailSubscriber": true,
      "estIsPointOfContact": true,
      "estRole": 0,
      "password": "deleteme9999",
      "timezoneOffset": "-8.0",
      "username": "deleteme999"
     },
    "id": "2861",
    "relationships": {
      "utilities": {
        "data": [
          {
            "id": "177",
            "type": "Utility"
          }
        ]
      }
    },
    "type": "User"
  }
}

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Example response:

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "User",
    "id": "2861",
    "attributes": {
      "appaId": "f3a69054-23ca-4dcf-9c84-c69c03fb65ab",
      "assetRole": null,
      "email": "deleteme@testing.com",
      "estIsEmailSubscriber": true,
      "estIsPointOfContact": true,
      "estRole": 0,
      "isPointOfContact": false,
      "requiresPasswordReset": false,
      "role": null,
      "timezoneOffset": -8.0,
      "username": "deleteme999"
    },
    "relationships": {
      "memberships": {
        "meta": {
          "count": 1
        },
        "data": [
          {
            "type": "Membership",
            "id": "4204"
          }
        ]
      },
      "utilities": {
        "meta": {
          "count": 1
        },
        "data": [
          {
            "type": "Utility",
            "id": "177"
          }
        ]
      }
    }
  }
}

Status Codes

200 OK – Utility updated
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.

Deactivate a User ¶

A user must have “admin” authorization to deactivate Users.

DELETE https://reliability.api.publicpower.org/v1/users/(int: user_id)/¶

Example request:

DELETE /v1/users/1213/ HTTP/1.1
Host: reliability.api.publicpower.org
Content-Type: application/vnd.api+json
Authorization: Bearer myaccesstoken

Request Headers

Authorization – Required OAuth token to authenticate. See Authentication docs.
Content-Type – Content-Type: application/vnd.api+json - JSON API IANA media type

Example response:

HTTP/1.1 204 No Content
Content-Type: application/vnd.api+json

Status Codes

204 No Content – User deleted
401 Unauthorized – You did not provide a valid Authorization: Bearer token.
403 Forbidden – Your user role is not authorized to access this endpoint.