Users API Reference

This guide covers the creating and managing platform users and business users through the API.

The User model

User are the people who use the platform. The user model is a representation of a user in the platform.

Properties

Name
id
Type
string
Field Type
Description
Unique identifier for the user.
Name
name
Type
string
Field Type
Description
The name of the user.
Name
email
Type
string
Field Type
Description
The email of the user.
Name
role
Type
string
Field Type
Description
The role of the user.
Name
business_id
Type
string
Field Type
Description
The business id of the user. (Only for business users)
Name
created_at
Type
timestamp
Field Type
Description
The created at timestamp.
Name
updated_at
Type
timestamp
Field Type
Description
The updated at timestamp.
Name
avatar
Type
string
Field Type
Description
The avatar of the user.
Name
abilities
Type
array
Field Type
Description
The abilities of the user.
Name
roles
Type
array
Field Type
Description
The roles of the user.
Name
is_owner
Type
boolean
Field Type
Description
Describes whether the user is the owner of the business.
Name
business
Type
object
Field Type
Description
Business object if the user is a business user.
Name
scope
Type
string
Field Type
Description
The scope of the user. One of platform or business.
Name
disabled
Type
boolean
Field Type
Description
Specify if the user is disabled.

User Scopes

Crater supports two types of scopes for users:

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

GETapi/v1/platform/users

List all platform users

This endpoint allows you to retrieve a paginated list of all your platform users.

Query Parameters

Name
limit
Type
integer
Field Type
optional
Description
Limit the number of users returned. (default is 10)
Name
page
Type
integer
Field Type
optional
Description
Page number for pagination. (default is 1)
Name
display_name
Type
string
Field Type
optional
Description
Filter records by name.
Name
email
Type
string
Field Type
optional
Description
Filter records by email.
Name
disabled
Type
boolean
Field Type
optional
Description
Filter records by disabled.

Request

GET

api/v1/platform/users

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

Response

{
  "data": [
    {
      "id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
      "name": "Candace Navarro",
      "email": "feugiat.sed@outlook.com",
      "role": "super admin",
      "created_at": 1715752545,
      "updated_at": 1715755443,
      "avatar": "https://crater-enterprise-dev.s3.us-west-2.amazonaws.com/media/8/trwfa?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3LTS5JCUDHHT4RM7%2F20240429%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20240429T100057Z&X-Amz-SignedHeaders=host&X-Amz-Expires=600&X-Amz-Signature=e8ce8b3e729ede2e7ab22712c15a68419e5ae32fc4c321d1db4a137ab5e9a2d8",
      "abilities": [],
      "scope": "platform",
      "disabled": false
    }, {...}
  ]
}

POSTapi/v1/platform/users

Create a platform user

This endpoint allows you to create a new platform user.

Request Body

Name
name
Type
string
Field Type
required
Description
The name of the user.
Name
email
Type
string
Field Type
required
Description
The email of the user.
Name
role
Type
string
Field Type
required
Description
The name of role.
Name
disabled
Type
boolean
Field Type
optional
Description
Specify if the user is disabled. default is false.

Request

POST

api/v1/platform/users

curl -X POST "https://payments.your-domain.com/api/v1/platform/users" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"name\": \"Candace Navarro\",
    \"email\": \"feugiat.sed@outlook.com\",
    \"role\": \"super admin\"
  }"

Response

{
  "data": {
    "id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "name": "Candace Navarro",
    "email": "feugiat.sed@outlook.com",
    "role": "super admin",
    "created_at": 1715752545,
    "updated_at": 1715755443,
    "avatar": "https://crater-enterprise-dev.s3.us-west-2.amazonaws.com/media/8/trwfa?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3LTS5JCUDHHT4RM7%2F20240429%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20240429T100057Z&X-Amz-SignedHeaders=host&X-Amz-Expires=600&X-Amz-Signature=e8ce8b3e729ede2e7ab22712c15a68419e5ae32fc4c321d1db4a137ab5e9a2d8",
    "abilities": [],
    "scope": "platform",
    "disabled": false
  }
}

GETapi/v1/platform/users/{id}

Retrieve a platform user

This endpoint allows you to retrieve a platform user by ID.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the user.

Request

GET

api/v1/platform/users/{id}

curl --request GET \
  "https://payments.your-domain.com/api/v1/platform/users/9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \

Response

{
  "data": {
    "id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "name": "Candace Navarro",
    "email": "feugiat.sed@outlook.com",
    "role": "super admin",
    "created_at": 1715752545,
    "updated_at": 1715755443,
    "avatar": "https://crater-enterprise-dev.s3.us-west-2.amazonaws.com/media/8/trwfa?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3LTS5JCUDHHT4RM7%2F20240429%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20240429T100057Z&X-Amz-SignedHeaders=host&X-Amz-Expires=600&X-Amz-Signature=e8ce8b3e729ede2e7ab22712c15a68419e5ae32fc4c321d1db4a137ab5e9a2d8",
    "abilities": [],
    "scope": "platform",
    "disabled": false
  }
}

PUTapi/v1/platform/users/{id}

Update a platform user

This endpoint allows you to update a platform user by ID.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the user.

Request Body

Name
name
Type
string
Field Type
optional
Description
The name of the user.
Name
email
Type
string
Field Type
optional
Description
The email of the user.
Name
role
Type
string
Field Type
optional
Description
The name of role.
Name
disabled
Type
boolean
Field Type
optional
Description
Specify if the user is disabled. default is false.

Request

PUT

api/v1/platform/users/{id}

curl -X PUT "https://payments.your-domain.com/api/v1/platform/users/9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"name\": \"Candace Navarro\",
    \"email\": \"feugiat.sed@outlook.com\",
    \"role\": \"super admin\"
  }"

Response

{
  "data": {
    "id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
    "name": "Candace Navarro",
    "email": "feugiat.sed@outlook.com",
    "role": "super admin",
    "created_at": 1715752545,
    "updated_at": 1715755443,
    "avatar": "https://crater-enterprise-dev.s3.us-west-2.amazonaws.com/media/8/trwfa?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3LTS5JCUDHHT4RM7%2F20240429%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20240429T100057Z&X-Amz-SignedHeaders=host&X-Amz-Expires=600&X-Amz-Signature=e8ce8b3e729ede2e7ab22712c15a68419e5ae32fc4c321d1db4a137ab5e9a2d8",
    "abilities": [],
    "scope": "platform",
    "disabled": false
  }
}

DELETEapi/v1/platform/users/{id}

Delete a platform user

This endpoint allows you to delete a platform user by ID.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the user.

Request

DELETE

api/v1/platform/users/{id}

curl -X DELETE "https://payments.your-domain.com/api/v1/platform/users/9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \

Response

{
  "id": "9bdf9dc1-6ca1-4e3c-bc91-84d0f607d6d8",
  "object": "User",
  "deleted": true
}

GETapi/v1/users

List all business users

This endpoint allows you to retrieve a paginated list of all your business users.

Query Parameters

Name
limit
Type
integer
Field Type
optional
Description
Limit the number of users returned. (default is 10)
Name
page
Type
integer
Field Type
optional
Description
Page number for pagination. (default is 1)
Name
display_name
Type
string
Field Type
optional
Description
Filter records by name.
Name
email
Type
string
Field Type
optional
Description
Filter records by email.
Name
disabled
Type
boolean
Field Type
optional
Description
Filter records by disabled. default is false.

Request

GET

api/v1/users

curl --request GET \
  "https://payments.your-domain.com/api/v1/users" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \

Response

{
  "data": [
    {
      "id": "9bec303c-abc1-4ed2-8bb2-311d8b18ef00",
      "name": "Joseph M. Adams",
      "email": "JosephMAdams@rhyta.com",
      "role": "administrator",
      "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
      "created_at": 1715752545,
      "updated_at": 1715755443,
      "avatar": "https://crater-enterprise-dev.s3.us-west-2.amazonaws.com/media/8/trwfa?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3LTS5JCUDHHT4RM7%2F20240429%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20240429T100057Z&X-Amz-SignedHeaders=host&X-Amz-Expires=600&X-Amz-Signature=e8ce8b3e729ede2e7ab22712c15a68419e5ae32fc4c321d1db4a137ab5e9a2d8",
      "abilities": [],
      "business": {},
      "scope": "business",
      "disabled": false
    }, {...}
  ]
}

POSTapi/v1/users

Create a business user

This endpoint allows you to create a new business user.

Request Body

Name
name
Type
string
Field Type
required
Description
The name of the user.
Name
email
Type
string
Field Type
required
Description
The email of the user.
Name
role
Type
string
Field Type
required
Description
The name of role.
Name
disabled
Type
boolean
Field Type
optional
Description
Specify if the user is disabled. default is false.

Request

POST

api/v1/users

curl -X POST "https://payments.your-domain.com/api/v1/users" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"name\": \"Joseph M. Adams\",
    \"email\": \"JosephMAdams@rhyta.com\",
    \"role\": \"administrator\"
  }"

Response

{
  "data": {
    "id": "9bec303c-abc1-4ed2-8bb2-311d8b18ef00",
    "name": "Joseph M. Adams",
    "email": "JosephMAdams@rhyta.com",
    "role": "administrator",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "created_at": 1715752545,
    "updated_at": 1715755443,
    "avatar": "https://crater-enterprise-dev.s3.us-west-2.amazonaws.com/media/8/trwfa?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3LTS5JCUDHHT4RM7%2F20240429%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20240429T100057Z&X-Amz-SignedHeaders=host&X-Amz-Expires=600&X-Amz-Signature=e8ce8b3e729ede2e7ab22712c15a68419e5ae32fc4c321d1db4a137ab5e9a2d8",
    "abilities": [],
    "is_owner": false,
    "business": {},
    "scope": "business",
    "disabled": false
  }
}

GETapi/v1/users/{id}

Retrieve a business user

This endpoint allows you to retrieve a business user by ID.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the user.

Request

GET

api/v1/users/{id}

curl --request GET \
  "https://payments.your-domain.com/api/v1/users/9bec303c-abc1-4ed2-8bb2-311d8b18ef00" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \

Response

{
  "data": {
    "id": "9bec303c-abc1-4ed2-8bb2-311d8b18ef00",
    "name": "Joseph M. Adams",
    "email": "JosephMAdams@rhyta.com",
    "role": "administrator",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "created_at": 1715752545,
    "updated_at": 1715755443,
    "avatar": "https://crater-enterprise-dev.s3.us-west-2.amazonaws.com/media/8/trwfa?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3LTS5JCUDHHT4RM7%2F20240429%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20240429T100057Z&X-Amz-SignedHeaders=host&X-Amz-Expires=600&X-Amz-Signature=e8ce8b3e729ede2e7ab22712c15a68419e5ae32fc4c321d1db4a137ab5e9a2d8",
    "abilities": [],
    "is_owner": false,
    "business": {},
    "scope": "business",
    "disabled": false
  }
}

PUTapi/v1/users/{id}

Update a business user

This endpoint allows you to update a business user by ID.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the user.

Request Body

Name
name
Type
string
Field Type
optional
Description
The name of the user.
Name
email
Type
string
Field Type
optional
Description
The email of the user.
Name
role
Type
string
Field Type
optional
Description
The name of role.
Name
disabled
Type
boolean
Field Type
optional
Description
Specify if the user is disabled. default is false.

Request

PUT

api/v1/users/{id}

curl -X PUT "https://payments.your-domain.com/api/v1/users/9bec303c-abc1-4ed2-8bb2-311d8b18ef00" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \
  --data "{
    \"name\": \"Joseph M. Adams\",
    \"email\": \"JosephMAdams@rhyta.com\",
    \"role\": \"administrator\"
  }"

Response

{
  "data": {
    "id": "9bec303c-abc1-4ed2-8bb2-311d8b18ef00",
    "name": "Joseph M. Adams",
    "email": "JosephMAdams@rhyta.com",
    "role": "administrator",
    "business_id": "995c98ce-cdd9-4ef6-b018-9c696cb07e9d",
    "created_at": 1715752545,
    "updated_at": 1715755443,
    "avatar": "https://crater-enterprise-dev.s3.us-west-2.amazonaws.com/media/8/trwfa?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3LTS5JCUDHHT4RM7%2F20240429%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20240429T100057Z&X-Amz-SignedHeaders=host&X-Amz-Expires=600&X-Amz-Signature=e8ce8b3e729ede2e7ab22712c15a68419e5ae32fc4c321d1db4a137ab5e9a2d8",
    "abilities": [],
    "is_owner": false,
    "business": {},
    "scope": "business",
    "disabled": false
  }
}

DELETEapi/v1/users/{id}

Delete a business user

This endpoint allows you to delete a business user by ID.

URL Parameters

Name
id
Type
string
Field Type
required
Description
The ID of the user.

Request

DELETE

api/v1/users/{id}

curl -X DELETE "https://payments.your-domain.com/api/v1/users/9bec303c-abc1-4ed2-8bb2-311d8b18ef00" \
  --header "Authorization: Bearer {YOUR_AUTH_TOKEN}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Business: 995c98ce-cdd9-4ef6-b018-9c696cb07e9d" \

Response

{
  "id": "9bec303c-abc1-4ed2-8bb2-311d8b18ef00",
  "object": "User",
  "deleted": true
}