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
orbusiness
.
- 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.
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
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
}, {...}
]
}
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
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
}
}
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
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
}
}
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
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
}
}
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
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
}
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
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
}, {...}
]
}
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
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
}
}
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
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
}
}
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
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
}
}
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
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
}