Setting Up Your Dev Environment

Check out our video tutorial on setting up your development environment.

Create an account#

To get started, go here to create an account for your organization. You will receive an email with steps to set your password. Once you log in with your new credentials, you can invite more users to Canopy by navigating to the Team page in the Admin dropdown in the top right. When selecting a role for your teammate, you can reference the RBAC documentation for further detail on the scope behind each role.

Machine To Machine Access#

Canopy provides two forms of accessing the API: human and machine. Both are powered by Auth0, meaning we never see your password.

After basic account creation, you have access to Canopy's UI. If you'd like to have programmatic access to the API, you will need to register an app. To do so, navigate to the App Keys page from the Admin dropdown in the top right, provide a name for your application, and click Generate App Keys. These credentials will be used by any non-interactive apps you may have, such as services running on your backend, command line tools, daemons, etc. This is also known as the M2M scenario - Machine to Machine.

This process uses the Client Credentials Flow (defined in OAuth 2.0 RFC 6749, section 4.4), in which the M2M app passes along its Client ID and Client Secret to authenticate itself and get a token.

You may create up to 5 apps. You can use these to test different environments or scenarios. You can deactivate unused apps in the UI. If you require more than 5 M2M apps, please reach out.

Using a Machine To Machine App#

Once you have generated a Client ID and Client Secret, you will need to exchange these for a token that will grant your app access to the API. The easiest way to do so is to download our Postman collection here. Once you have it opened in Postman, navigate to the Auth Folder, and open the Request Access Token scenario. The body of the request will be pre-populated with the client_id and client_secret environment variables. This is what you should see:

Postman request to get token

Instead of directly changing these credentials in the body, we highly recommend setting them in the Environment once and using them from there. The UAT that you see in the dropdown in the top right of the image is a sample environment. Once you have done so and run the request, the returned token will be automatically added to your environment as well, and appended to every subsequent request.

Depending on your role (which will by proxy be the role of your M2M app), your app will now be able to access the API. The generated token is valid for 24 hours. After that, you will need to re-authenticate and generate a fresh token to access the API.

RBAC#

We restrict system access using RBAC (Role-Based Access Control).

There are three core entities:

ROLE <-> ACTION <-> RESOURCE

An example would be:

admin <-> can create <-> products

The combination of ACTION and RESOURCE is a PERMISSION. By defining a granular set of permissions for each role, we are able to maintain fine-grained control over every resource behind this API.

ABAC#

We integrate attributes, a concept central to ABAC (Attribute-Based Access Control) to enhance the RBAC system with even more granular controls based on context. This results in a more robust, hybrid RBAC-ABAC mode of access control.

Roles#

Roles without an _M2M suffix are interactive (non-programmatic) roles. These can only interact with the API from the browser through the password authentication flow and are thus more limited.

Terminology#

M2M

Machine-to-Machine. Expects a Client Credentials flow as per the Oauth2.0 specification.

R

The READ action. Corresponds to GET request method.

W

The WRITE action. Corresponds to POST, PUT, and PATCH request methods.

D

The DELETE action. Corresponds to DELETE request method.

Note: all deletes in our system are soft deletes to maintain immutability and auditability.

RBAC