API Reference

Authorization and Permissions

Wingspan RBAC Model overview.

Wingspan's Role-Based Access Control (RBAC) model is a system designed to manage and enforce fine-grained access control within the platform. It consists of two primary components: Authorizations and Scope Groups. This model allows for flexible and granular control over user permissions and access rights across various services and resources.

Components

1. Authorizations

Authorizations form the foundation of the RBAC model. They define the relationship between a requesting user (the user seeking access) and a principal user (the user or resource being accessed).

Key Concepts:

  • Authorization ID: A unique identifier for each authorization.
  • Requesting User ID: The ID of the user requesting access.
  • User ID: The ID of the principal user or resource being accessed.
  • Allowed Scope: A specific scope that the authorization grants access to.
  • Allowed Scope Group ID: Reference to a scope group that the authorization grants access to.
  • Allowed Action: Defines the type of access granted (Read or Write).

Authorization Actions:

  • Read: Allows the requesting user to view or access information.
  • Write: Allows the requesting user to modify or create information.

Implementation Details:

  • The system supports creating, reading, updating, and deleting authorizations via API endpoints.
  • Authorizations can be associated with individual scopes or scope groups.

2. Scope Groups

Scope Groups allow for the grouping of multiple scopes under a single identifier. This simplifies the process of granting multiple permissions at once and helps in managing complex permission structures.

Key Concepts:

  • Scope Group ID: A unique identifier for each scope group.
  • Name: A human-readable name for the scope group.
  • Scopes: An array of scope strings that belong to the group.

Implementation Details:

  • The system supports creating, reading, updating, and deleting scope groups via API endpoints.
  • Authorizations can reference scope groups instead of individual scopes for broader access control.

Available Scope Groups:

Wingspan currently maintains the following internally managed scope groups:

  1. Finances (ID: mnTAr3m5HJLNoKdL8ntm10)

    • Scopes: bookkeeping.service, bookkeeping.transaction, bookkeeping.withholdingTransaction, bookkeeping.businessBankingAccount, bookkeeping.businessBankingBalance, bookkeeping.pendingTransaction, payments.payoutSettings, payments.card, payments.code

  2. Admin (ID: Qk5amjWDHoHeLXN1DCR0yk)

    • Scopes: * (all scopes)

  3. Documents (ID: 608219e297b39a1ddd573352)

    • Scopes: files.files

  4. Payments (ID: qX_ZUDUzFkmQDyZeGmR3XF)

    • Scopes: payments.invoice, payments.payable, payments.invoice-template, payments.memberClient, payments.service, payments.additionalData, payments.customField, payments.payrollSettings, payments.payoutSettings, payments.paymentSettings, payments.deduction, payments.taxForm, search.invoice-template, search.invoice

  5. Collaborators (ID: 6270714525b71672ee07409d)

    • Scopes: payments.memberClient, payments.additionalData, payments.customField, payments.service, payments.eligibilityRequirement, files.esig, search.search, payments.payerPayee, payments.engagement

  6. Base (ID: 6081a54b52e07d57418528eb)

    • Scopes: users.activity, users.user, users.member, users.client, users.account, users.authorization, experiments.experiment, users.subscription, notifications.Notification

Organization Accounts and Sub-accounts

The RBAC model supports hierarchical structures for organization accounts:

  • Organization accounts can have sub-accounts with inherited permissions.
  • The system provides methods to verify access to sub-accounts and retrieve authorized sub-accounts for a user.

Read more about Org Accounts

API Endpoints for Authorization Management

The system provides several API endpoints for managing authorizations and retrieving authorized scopes. Here are the key endpoints and their functionalities:

Create Authorization

  • Endpoint: POST /users/authorization
  • Description: Creates a new authorization for a user.
  • Request Body: 
    {
  "requestingUserId": "string",
  "userId": "string",
  "allowedScope": "string",
  "allowedScopeGroupId": "string",
  "allowedAction": "Read" | "Write"
}
  • Response: Returns the created authorization object.

Retrieve Authorizations

  • Endpoint: GET /users/authorization
  • Description: Retrieves all authorizations for the authenticated user.
  • Response: Returns an array of authorization objects.

Retrieve Specific Authorization

  • Endpoint: GET /users/authorization/{authorizationId}
  • Description: Retrieves details of a specific authorization.
  • Response: Returns the authorization object.

Update Authorization

  • Endpoint: PATCH /users/authorization/{authorizationId}
  • Description: Updates an existing authorization.
  • Request Body: Similar to the create request, but fields are optional.
  • Response: Returns the updated authorization object.

Delete Authorization

  • Endpoint: DELETE /users/authorization/{authorizationId}
  • Description: Deletes a specific authorization.
  • Response: Returns a success message.

Retrieve Authorized Scopes

  • Endpoint: GET /users/authorized-scopes
  • Description: Retrieves all authorized scopes for the authenticated user.
  • Response: Returns an object with Read and Write scopes.

Retrieve Authorized Scope Groups

  • Endpoint: GET /users/authorized-scope-groups
  • Description: Retrieves all authorized scope groups for the authenticated user.
  • Response: Returns an array of scope group objects.