Check out our video tutorial on setting up your development environment.
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.
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.
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_secret environment variables. This is what you should see:
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.
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
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.
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 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.
Machine-to-Machine. Expects a Client Credentials flow as per the Oauth2.0 specification.
READ action. Corresponds to
GET request method.
WRITE action. Corresponds to
PATCH request methods.
DELETE action. Corresponds to
DELETE request method.
Note: all deletes in our system are soft deletes to maintain immutability and auditability.