Users

Types of Users

Organizational

Organizational users belong to a root organization and have access to the finance portal to create and manage resources in the system. Examples would be partner employees and palmetto employees.

Account

Account users belong to one more specific accounts. These users can only view those accounts and resources that belong to those accounts, they do not have access to any organizational resources. These types of users are used to access the palmetto consumer application. Examples would be the end user that has solar panels installed on their house.

Machine to Machine

Machine to Machine users are programmatic users that, like organizational users, belong to a root organization, but do not have access to the finance portal and may only log in via the API Organizational users are prevented from using this auth flow for security reasons.

Authentication & Authorization

The palmetto finance system implements OAuth 2 for authentication & authorization (auth n/z). The system uses access tokens in the form of JSON Web Tokens, or JWT’s. Sending tokens via the Authorization header in Bearer format as well as an access_token cookie are both supported.

await fetch(url, {
  method: 'post',
  body: JSON.stringify({...}}),
  headers: {
        'Authorization': `Bearer ${accessToken}`,
        ...
    }
});

permissions

Currently there are three basic permissions admin, ‘Editor’, and ‘Reader’. These permissions control access to features and resource editing.

Permission	Description
admin	view and edit all resource
editor	view and edit all resource except editing users
reader	View all all resources

Obtaining a Token

Authorization Code Grant Flow

For client and/or interactive applications the authorization code grant flow should be used to obtain both the ID Token and the Access Token.

Machine to Machine

When interacting with the palmetto finance API, ideal user credentials are flown through the partner service to the finance service. However, there are use cases where this is not possible or does not make sense. In those cases a user can use the login endpoint to acquire an access_token for a machine to machine user

import fetch from 'node-fetch';

const url = `{envBaseUrl}/api/auth/login&org=${aliasOfOrganizationToImpersonate}`;
const response = await fetch(url, {
  method: 'post',
  body: JSON.stringify({
    username: 'string',
    password: 'string',
  }),
  headers: { 'Content-Type': 'application/json' },
});
const data = await response.json();
console.log(data.access_token);