Roles API Reference

This guide covers the creating and managing roles in the platform.

The Role model

The role model is a representation of a role in the platform. It has the following properties:

Properties

  • Name
    id
    Type
    string
    Field Type
    Description

    Unique identifier for the role.

  • Name
    name
    Type
    string
    Field Type
    Description

    The name of the role.

  • Name
    description
    Type
    string
    Field Type
    Description

    The description of the role.

  • Name
    scope
    Type
    string
    Field Type
    Description

    The scope of the role. One of platform or business. (cant be changed once created)

  • Name
    created_at
    Type
    timestamp
    Field Type
    Description

    The date and time the role was created.

  • Name
    abilities
    Type
    array
    Field Type
    Description

    The abilities of the role.

Role / User Scopes

There are 2 types of users in Crater:

  • Platform Scope: Used to manage businesses, users, and other resources across the platform. For example the super admin user & other of the platform.
  • Business Scope: Used to manage resources within a specific business. For example the business owner or accountant. of a specific business.

Abilities

Abilities define the level of access a given role will have to resources in Crater.

NameResourceScope
view-businessBusinessplatform
create-businessBusinessplatform
edit-businessBusinessplatform
delete-businessBusinessplatform
view-access-logAccessLogplatform
view-roleRoleplatform
manage-roleRoleplatform
view-api-logApiLogplatform
view-platform-settingSettingsplatform
edit-platform-settingSettingsplatform
view-webhookWebhookplatform
create-webhookWebhookplatform
edit-webhookWebhookplatform
delete-webhookWebhookplatform
view-eventEventplatform
view-email-templateEmailTemplateplatform
create-email-templateEmailTemplateplatform
edit-email-templateEmailTemplateplatform
delete-email-templateEmailTemplateplatform
view-platform-userUserplatform
create-platform-userUserplatform
edit-platform-userUserplatform
delete-platform-userUserplatform
edit-business-informationBusinessbusiness & platform
view-business-statsBusinessbusiness & platform
manage-business-settingsBusinessbusiness & platform
manage-notificationsBusinessbusiness & platform
edit-business-informationSettingsbusiness & platform
view-userUserbusiness & platform
create-userUserbusiness & platform
edit-userUserbusiness & platform
delete-userUserbusiness & platform
view-customerCustomerbusiness & platform
create-customerCustomerbusiness & platform
edit-customerCustomerbusiness & platform
delete-customerCustomerbusiness & platform
view-vendorVendorbusiness & platform
create-vendorVendorbusiness & platform
edit-vendorVendorbusiness & platform
delete-vendorVendorbusiness & platform
view-estimateEstimatebusiness & platform
create-estimateEstimatebusiness & platform
edit-estimateEstimatebusiness & platform
delete-estimateEstimatebusiness & platform
send-estimateEstimatebusiness & platform
approve-reject-estimateEstimatebusiness & platform
view-invoiceInvoicebusiness & platform
create-invoiceInvoicebusiness & platform
edit-invoiceInvoicebusiness & platform
delete-invoiceInvoicebusiness & platform
send-estimateInvoicebusiness & platform
approve-invoiceInvoicebusiness & platform
pay-invoiceInvoicebusiness & platform
view-paymentPaymentbusiness & platform
send-paymentPaymentbusiness & platform
view-recurring-invoiceRecurringInovicebusiness & platform
create-recurring-invoiceRecurringInovicebusiness & platform
edit-recurring-invoiceRecurringInovicebusiness & platform
delete-recurring-invoiceRecurringInovicebusiness & platform
view-itemItembusiness & platform
create-itemItembusiness & platform
edit-itemItembusiness & platform
delete-itemItembusiness & platform
view-noteNotebusiness & platform
create-noteNotebusiness & platform
edit-noteNotebusiness & platform
delete-noteNotebusiness & platform
view-tax-typeTaxtypebusiness & platform
create-tax-typeTaxtypebusiness & platform
edit-tax-typeTaxtypebusiness & platform
delete-tax-typeTaxtypebusiness & platform
view-payment-reminderPaymentReminderbusiness & platform
create-payment-reminderPaymentReminderbusiness & platform
edit-payment-reminderPaymentReminderbusiness & platform
delete-payment-reminderPaymentReminderbusiness & platform
view-payment-methodPaymentMethodbusiness & platform
create-payment-methodPaymentMethodbusiness & platform
edit-payment-methodPaymentMethodbusiness & platform
delete-payment-methodPaymentMethodbusiness & platform
view-payment-onboarding-linkPaymentOnboardingLinkbusiness & platform
create-payment-onboarding-linkPaymentOnboardingLinkbusiness & platform
edit-payment-onboarding-linkPaymentOnboardingLinkbusiness & platform
delete-payment-onboarding-linkPaymentOnboardingLinkbusiness & platform
view-reportReportbusiness & platform
view-audit-logAuditLogbusiness & platform
view-balance-sheetLoanBalancebusiness & platform
manage-integrationIntegrationbusiness & platform
GETapi/v1/platform/roles

List all roles

This endpoint allows you to retrieve a paginated list of all roles.

Query Parameters

  • Name
    name
    Type
    integer
    Field Type
    optional
    Description

    Filter roles by name.

  • Name
    scope
    Type
    integer
    Field Type
    optional
    Description

    Filter roles by scope. One of platform or business. (if not passed or passed all it will return all roles).

Request

GET
api/v1/platform/roles
curl --request GET \
  "https://payments.your-domain.com/api/v1/platform/roles" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \

Response

{
  "data": [
    {
      "id": "0073c5c8-637f-491d-bcb8-325210f1fd2e",
      "name": "Admin",
      "description": "Admin role",
      "scope": "platform",
      "created_at": 1714040338,
      "abilities": [
        {
          "name": "view-business",
          "scope": "platform"
        }, {...}
      ]
    }, {...}
  ]
}
POSTapi/v1/platform/roles

Create a role

This endpoint allows you to create a new role in the platform.

Query Parameters

  • Name
    name
    Type
    string
    Field Type
    required
    Description

    The name of the role.

  • Name
    description
    Type
    string
    Field Type
    required
    Description

    The description of the role.

  • Name
    scope
    Type
    string
    Field Type
    required
    Description

    The scope of the role. One of platform or business.

  • Name
    abilities
    Type
    array
    Field Type
    required
    Description

    The abilities of the role. You can check the list of abilities here.

Request

POST
api/v1/platform/roles
curl --request POST \
  "https://payments.your-domain.com/api/v1/platform/roles" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"name\": \"Admin\",
    \"description\": \"Admin role\",
    \"scope\": \"platform\",
    \"abilities\": [\"view-customer\", \"create-customer\"]
  }"

Response

{
  "data": {
    "id": "0073c5c8-637f-491d-bcb8-325210f1fd2e",
    "name": "Admin",
    "description": "Admin role",
    "scope": "platform",
    "created_at": 1714040338,
    "abilities": [
      {
        "name": "view-business",
        "scope": "platform"
      }, {...}
    ]
  }
}
GETapi/v1/platform/roles/{role_id}

Retrive a role

This endpoint allows you to retrieve a role by its ID.

URL Parameters

  • Name
    role_id
    Type
    string
    Field Type
    required
    Description

    The ID of the role.

Request

GET
api/v1/platform/roles/{role_id}
curl --request GET \
  "https://payments.your-domain.com/api/v1/platform/roles/0073c5c8-637f-491d-bcb8-325210f1fd2e" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \

Response

{
  "data": {
    "id": "0073c5c8-637f-491d-bcb8-325210f1fd2e",
    "name": "Admin",
    "description": "Admin role",
    "scope": "platform",
    "created_at": 1714040338,
    "abilities": [
      {
        "name": "view-business",
        "scope": "platform"
      }, {...}
    ]
  }
}
PUTapi/v1/platform/roles/{role_id}

Update a role

This endpoint allows you to update a role by its ID.

URL Parameters

  • Name
    role_id
    Type
    string
    Field Type
    required
    Description

    The ID of the role.

Body Parameters

  • Name
    name
    Type
    string
    Field Type
    optional
    Description

    The name of the role.

  • Name
    description
    Type
    string
    Field Type
    optional
    Description

    The description of the role.

  • Name
    abilities
    Type
    array
    Field Type
    optional
    Description

    The abilities of the role.

Request

PUT
api/v1/platform/roles/{role_id}
curl --request PUT \
  "https://payments.your-domain.com/api/v1/platform/roles/0073c5c8-637f-491d-bcb8-325210f1fd2e" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"name\": \"Admin\",
    \"description\": \"Admin role\",
    \"abilities\": [\"view-customer\", \"create-customer\"]
  }"

Response

{
  "data": {
    "id": "0073c5c8-637f-491d-bcb8-325210f1fd2e",
    "name": "Admin",
    "description": "Admin role",
    "scope": "platform",
    "created_at": 1714040338,
    "abilities": [
    {
      "name": "view-business",
      "scope": "platform"
    }, {...}
  ]
}
}
DELETEapi/v1/platform/roles/{role_id}

Delete a role

This endpoint allows you to delete a role by its ID.

URL Parameters

  • Name
    role_id
    Type
    string
    Field Type
    required
    Description

    The ID of the role.

Request

DELETE
api/v1/platform/roles/{role_id}
curl --request DELETE \
  "https://payments.your-domain.com/api/v1/platform/roles/0073c5c8-637f-491d-bcb8-325210f1fd2e" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Response

{
  {
    "id": "0073c5c8-637f-491d-bcb8-325210f1fd2e",
    "object": "Role",
    "deleted": true
  }
}