Access Roles

Overview

Access roles are sets of permissions that are assigned to users.

They limit users' read and write access on endpoints.

Get Access Roles

Returns data from all access roles.

GET /accessroles

Endpoint URL

https://www.cotalker.com/api/v2/accessroles

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Admin	Grants access to the endpoint.	Required	true

Query Parameters

Parameter	Description	Type	Required	Notes
limit	Limits the amount of access roles returned in the response.	number	Optional	By default, the limit is set to 10.
page	Makes the response display data from the indicated page number.	number	Optional	Best used in combination with the "limit" parameter.
count	Adds the counter field with the total amount of access roles.	boolean	Optional
isActive	Returns access roles according to their accessroles.active status.	string	Optional	Options are: all, true, false
ids	Returns access roles with the indicated ObjectIds in their accessroles._id field.	ObjectId<COTAccessRole>[ ]	Optional
search	Returns access roles that match the keyword. Searches through the values of accessroles.name, accessroles.permissions, and accessroles.description fields.	string	Optional	See COTAccessRole for data model details.
debug	Adds the debug field with error notifications and query values.	string	Optional	Option: true

Request Sample

cURL (default)

Request returns all access roles:

curl --location --request GET 'https://www.cotalker.com/api/v2/accessroles' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

cURL (query)

Returns access roles that match search query:

curl --location --request GET 'https://www.cotalker.com/api/v2/accessroles?debug=true&search=admin access' \
--header 'Admin: true' 
--header 'Authorization: Bearer $ACCESS_TOKEN' 

Response Sample

Responses follow the COTAccessRole data model.

---

Get an Access Role by Id

Returns the access role indicated by the Id.

GET /accessroles/{id}

Endpoint URL

https://www.cotalker.com/api/v2/accessroles/{id}

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the access role that is to be returned.	ObjectId<COTAccessRole>	Required

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Admin	Grants administrative access to view the access role.	Required	true

Query Parameters

Parameter	Description	Type	Required	Notes
debug	Adds the debug field with error notifications.	string	Optional	Option: true

Request Sample

curl --location --request GET 'https://www.cotalker.com/api/v2/accessroles/619648a6f27b4eb1a9e319ba' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' 

Response Sample

The response follows the COTAccessRole data model.

---

Create a New Access Role

Creates a new access role within the company.

POST /accessroles

Endpoint URL

https://www.cotalker.com/api/v2/accessroles

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Admin	Grants administrative access to create an access role.	Required	true
Content-Type	Sets the body's format.	Required	application/json

Query Parameters

Parameter	Description	Type	Required	Notes
debug	Adds the debug field with error notifications.	string	Optional	Option: true

Request Body

Only required fields are listed below. For a complete schema description, please go to the COTAccessRole data model. Unrequired fields that are not submitted are either filled in automatically or left blank.

Element	Description	Type	Required	Notes
name	Indicates the access role's name.	string	Required
permissions	Set of permissions assigned to the access role.	string[ ]	Required	List of default permissions

Request Sample

Access role created with the minimum required fields:

curl --location --request POST 'https://www.cotalker.com/api/v2/accessroles' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "audit",
    "permissions": [
        "admin-access"
    ]
}'

Response Sample

Go to COTAccessRole for a complete description of the response.

{
    "active": true,
    "permissions": [
        "admin-access"
    ],
    "_id": "619648a6f27b4eb1a9e319ba",
    "name": "audit",
    "company": "6196489edb1ac3d5da55e198",
    "__v": 0
}

---

Update an Access Role

Updates, edits, or adds information to an existing access role.

PATCH /accessroles/{id}

Endpoint URL

https://www.cotalker.com/api/v2/accessroles/{id}

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the access role that is to be modified.	ObjectId<COTAccessRole>	Required

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Admin	Grants administrative access to modify the access role.	Required	true
Content-Type	Sets the body's format.	Required	application/json

Query Parameters

Parameter	Description	Type	Required	Notes
debug	Adds the debug field with error notifications.	string	Optional	Option: true

Request Body

Only the fields that are being updated or added are required to be put into the body. For a complete schema description, please go to the COTAccessRole data model.

Request Sample

curl --location --request PATCH 'https://www.cotalker.com/api/v2/accessroles/619648a6f27b4eb1a9e319ba' \
--header 'Admin: true' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "description": "Grants auditors read-only permissions to specific endpoints.",
    "permissions": ["admin-access", "admin-groups-read"]
}'

Response Sample

Go to COTAccessRole for a complete description of the response.

{
    "active": true,
    "permissions": [
        "admin-access",
        "admin-groups-read"
    ],
    "_id": "619647ffda52400007d7ffdc",
    "name": "audit",
    "company": "6136968b580aaf2b0e49d844",
    "__v": 2,
    "description": "Grants auditors read-only permissions to specific endpoints."
}

---