Skip to content

Sub-User Management#

The Yale/August system distinguishes between two types of users:

  • Normal users - These users are fully authenticated. They have an email, phone number, and a password, and they log in on their registered devices using two-factor authentication.
  • Sub-users - These users are unverified. They do not have their own identifiers (an email or phone number) but are linked to a parent account. They can be granted PIN or app access to specific devices.

Required

You must have the users:sub-user:create scope enabled on your OAuth credential to create, manage, or delete sub-users.

Get a list of sub-users#

General API call format for getting a list of sub-users#

The following API call will return a list of sub-users associated with your partner.

GET /partners/sub-user

x-august-api-key: <your API key>
x-august-access-token: <your partner user's access token>

This API endpoint has pagination where the response data is broken down into subsets called pages. There are 2 optional query parameters that can be passed in the request:

  • page - The current page (subset) of response data. This page must be a positive, whole number. If no page is specified, the value is defaulted to 1. The API will return an error if the page value entered is higher than the total number of pages of sub-user data.
  • pageSize - The maximum amount of records that can be included in each page (subset returned in a single API response). This must be a positive, whole number between 1 and 1000. If no pageSize is specified, the value is defaulted to 1000.

The API will respond with HTTP status 200 and a response body containing a list of sub-users.

{
  "totalRecords": 1002,
  "currentPage": 1,
  "pageRecordStart": 1,
  "pageRecordEnd": 1000,
  "totalPages": 2,
  "subUsers": [
    {
      "userID": "00000000-0000-0000-0000-000000000001",
      "firstName": "TEST",
      "lastName": "SUBUSER1",
      "userOwnerID": "00000000-0000-0000-0000-123400000000",
      "partnerUserID": "test-partnerUserID1"
    },
    {
      "userID": "00000000-0000-0000-0000-000000000002",
      "firstName": "TEST",
      "lastName": "SUBUSER2",
      "userOwnerID": "00000000-0000-0000-0000-123400000000",
      "partnerUserID": "test-partnerUserID2"
    },
    ...
  ]
}

The fields included in the response body are:

  • totalRecords - The total number of sub-users that exists in our system for the current partner.
  • currentPage - The current page (subset) of response data.
  • pageRecordStart - The first record in the current page (subset) of response data.
  • pageRecordEnd - The last record in the current page (subset) of response data.
  • totalPages - The total number of pages (subsets) of response data.
  • subUsers - An array of sub-users.
    • userID - The August/Yale userID associated with the sub-user.
    • firstName - The first name associated with the sub-user.
    • lastName - The last name associated with the sub-user.
    • userOwnerID - The August/Yale userID associated with user owner of the sub-user.
    • partnerUserID - An arbitrary string that is associated with this sub-user. Each sub-user has a unique partnerUserID provided by the partner upon sub-user creation. A partnerUserID is not globally unique across other partners. This is not the same partnerUserID as used in POST /locks/:lockID/pins. This endpoint should not be used for unverified users created using POST /locks/:lockID/pins.

API call format for getting the next page of sub-user data#

GET /partners/sub-user?page=2

x-august-api-key: <your API key>
x-august-access-token: <your partner user's access token>

The above example will return the second page of sub-user data.

{
  "totalRecords": 1002,
  "currentPage": 2,
  "pageRecordStart": 1001,
  "pageRecordEnd": 1002,
  "totalPages": 2,
  "subUsers": [
    {
      "userID": "00000000-0000-0000-0000-000000001001",
      "firstName": "TEST",
      "lastName": "SUBUSER1001",
      "userOwnerID": "00000000-0000-0000-0000-123400000000",
      "partnerUserID": "test-partnerUserID1001"
    },
    {
      "userID": "00000000-0000-0000-0000-000000001002",
      "firstName": "TEST",
      "lastName": "SUBUSER1002",
      "userOwnerID": "00000000-0000-0000-0000-123400000000",
      "partnerUserID": "test-partnerUserID1002"
    }
  ]
}

Create a sub-user#

Required

You must have the users:sub-user:create scope enabled on your OAuth credential to create a sub-user.

The following API call can be used in 3 different ways:

  1. To create a new, non-existing sub-user associated with your partner based upon the partnerUserID.
  2. To retrieve the access token for an existing sub-user.
  3. If there is no refresh token presented to the caller. As such, this is also used to refresh the access token for that sub-user.
POST /partners/sub-user

x-august-api-key: <your API key>
x-august-access-token: <your partner user's access token>

{
    "partnerUserID": "test-partnerUserID",
    "firstName": "test-first-name",
    "lastName": "test-last-name"
}

All fields in the request body are required.

  • partnerUserID - An arbitrary string that is associated with this sub-user. Each sub-user must have a unique partnerUserID for your partnerID. A partnerUserID is not globally unique across other partners.
  • firstName - The first name of the sub-user.
  • lastName - The last name of the sub-user.

The API will immediately respond with HTTP status 200 and a response body.

{
  "access_token": "...",
  "firstName": "test-first-name",
  "lastName": "test-last-name",
  "userCreated": true,
  "userID": "00000000-0000-0000-0000-000000001003"
}
  • access_token: The access token associated with this sub-user to be used for August API requests.
  • firstName - The first name of the sub-user.
  • lastName - The last name of the sub-user.
  • userCreated: A boolean value indicating that a August/Yale user was created.
  • userID: The August/Yale userID associated with the sub-user.

Delete a sub-user#

The following API call is used to delete a sub-user associated with your partner.

Note

This endpoint is also used for a general 'factory reset' of a user.

DELETE /users/:userID?source=partnerName

x-august-api-key: <your API key>
x-august-access-token: <your partner sub-user's access token>

Required

You must use the access token associated with the sub-user to delete using this method. This is the access token that was generated and returned in the response body of POST /partners/sub-user

All parameters in the request are required.

  • userID - The August/Yale userID associated with the sub-user.
  • source - The origin of this API request. You can enter your partner name here.

The API will immediately respond with HTTP status 200 and a response body indicating the sub-user was successfully removed.

{
  "message": "success"
}