Authorization & Scopes

Your access to the Prospero API is limited by the scopes assigned to the authenticated user. Prospero's scopes are granular, giving you maximum control over the entities users can access and the actions they can perform.

Scopes

Prospero scopes are defined in a hierarchical structure, where more granular scopes take precedence over coarser ones. The scopes are described and best visualized as a nested object:

Code
 
enum Permission {
  NO_ACCESS = 0,
  READ = 1,
  COMMENT = 2,
  UPDATE = 3,
  CREATE = 4,
  DELETE = 5,
}

interface UserAuthorization {
  default: Permission;
  settings: {
    default: Permission;
    organization: Permission;
    membership: Permission;
    billing: Permission;
    calendarIntegrations: Permission;
  };
  entities: {
    default: Permission;
    projects: { default: Permission };
    locations: { default: Permission };
    people: { default: Permission };
    items: { default: Permission };
    consumables: { default: Permission };
    tags: { default: Permission };
    files: { default: Permission };
    events: {
      default: Permission;
      byProject: { [k: Id]: Permission };
    };
    bookings: {
      default: Permission;
      byBookingModule: { [k: Id]: Permission };
    };
    bookingModules: { default: Permission };
    portals: { default: Permission };
    customers: { default: Permission };
    offers: { default: Permission };
    invoices: { default: Permission };
  };
}

When determining authorization for a given API endpoint, Prospero works bottom-up, from most granular scope to coarsest, to determine the user's permission level.

For example, if a user is attempting to create a new Project, Prospero will first check the user's projects scope (corresponding to entities.projects.default in the interface above). If this scope has a permission level greater than or equal to Permission.CREATE (Permission.CREATE or Permission.DELETE), they will be authorized to create a new Project. If the permission level is less than Permission.CREATE, the user is unauthorized and will be denied access. If the projects scope is absent, Prospero will check the user's entities scope (corresponding to entities.default), then finally, if the entities scope is absent, Prospero will check the user's default scope (corresponding to default).