User administration

Our customers (called "intermediaries" in API code) can administer users using their api keys.

Create user with externalId

You can create a user, using an ID you have control over, either something randomly generated and stored on your side, or a customer ID or maybe even a phone number. We call this externaId in our API.

mutation {
	addUser(input: { userIdentifier: { externalUser: { externalId: "END_USER_ID" } } }) {
	  success
	  user {
		…
		userIdentifier {
			…
		}
	}
}

Give the user permissions to one or more devices

Based on what is stored in your databases about which users own or otherwise have access to which devices, you can add permissions in our API. The devices can be identified using the deviceId (eight characters) or the meterId (serial number of power meter).

mutation {
	addDevicePermissions(input: {
		deviceIdentifiers: [{ meterId: "METERID" }]  # or deviceId
		userIdentifier: { externalUser: { externalId: "END_USER_ID" } }
	}) {
		success
		modifiedPermissions { … }
		user { … }
	}
}

Create a session for this user, returning a token for other requests

You also have to add a user session to get an accessToken you can store in the user's app. This token can now be used to fetch data without going through your (customer) systems.

mutation {
	addUserSession(input: { userIdentifier: { externalUser: { externalId: "END_USER_ID" } } } ) {
		success
		user { … }
		session {
			accessToken
		}
	}
}

You will then use the returned accessToken as described elsewhere

Authorization: Bearer ACCESS_TOKEN

Optional: Check order status(es) for the user

To check the status of a user's orders:

query {
	ordersForUser(input: { externalUserId: "END_USER_ID" }) {
		orders {
			orderId
			orderStatus
			deviceId
			trackingLink
			…
		}
	}
}

When an order is SHIPPED there should be values in the deviceId and trackingLink fields.

Other user administration API calls

There are several other API calls for user administration that are based on externalId and more or less follows the same syntax

• removeUser
• removeDevicePermissions
• addChargingPermission
• removeChargingPermission

Implementation notes

The session is valid until 30 days after last user activity (updated on user activity). Because of this, you can implement error handling that will run the create/permission/session calls again. Some of our customers find it easier to run the create/permission/session calls each time the user opens the app. We are considering implementing a check for valid user/session/permission.