B2B Edition
B2B Edition APIs
Server to Server Management APIs
Company
Company Roles and Permissions

Company Roles and Permissions

Get All Company Permissions

GET /companies/permissions

Request

Returns a list of all predefined and custom Company permissions.

Authentication

  • authToken in header

Parameters

  • q in query - string
    Enter a Company permission name to return partial and exact matches.

example

curl --request GET \
--url https://api-b2b.bigcommerce.com/api/v3/io/companies/permissions \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json

  • code    integer

  • data    array[object]

  • meta    object

200 - SUCCESS

{
"code": 200,
"data": [
{
"id": 1,
"name": "Get addresses",
"description": "Get addresses",
"code": "get_addresses",
"isCustom": false,
"moduleName": "address"
}
],
"meta": {
"message": "SUCCESS"
}
}

Create a Company Permission

POST /companies/permissions

Request

Create a custom Company permission.

Note that the permission’s name and code values cannot match an existing permission.

Authentication

  • authToken in header

Body

object | application/json

  • name    string
    required

    The name of the Company permission.
    <= 200 characters
    Example: Get addresses

  • description    string
    required

    The simple description for the Company permission. See Permission Codes for a more detailed description of each predefined Company permission.
    <= 512 characters
    Example: Get addresses

  • code    string
    required

    The code string of the Company permission.
    <= 50 characters
    Example: get_addresses

  • moduleName    string

    The name of the module to which the permission belongs. This corresponds to the organizational section containing the permission when managing Company roles from the B2B Edition control panel.
    <= 50 characters
    Example: address

Example 1

{
"name": "Get addresses",
"description": "Get addresses",
"code": "get_addresses",
"moduleName": "address"
}

Response

OK

Body

object | application/json

  • code    integer

    Default: 200

  • data    object

  • meta    object

200 - SUCCESS

{
"code": 200,
"data": {
"id": 1,
"name": "Get addresses",
"description": "Get addresses",
"code": "get_addresses",
"isCustom": false,
"moduleName": "address"
},
"meta": {
"message": "SUCCESS"
}
}

Update a Company Permission

PUT /companies/permissions/{permissionId}

Request

Updates an existing custom Company permission.

Predefined permissions cannot be updated.

Authentication

  • authToken in header

Parameters

  • permissionId in path - integer
    required
    The unique identifier for a Company permission.
The name and code are unique within the same store.

Body

object | application/json

  • name    string
    required

    The name of the Company permission.
    <= 200 characters
    Example: Get addresses

  • description    string
    required

    The simple description for the Company permission. See Permission Codes for a more detailed description of each predefined Company permission.
    <= 512 characters
    Example: Get addresses

  • code    string
    required

    The code string of the Company permission.
    <= 50 characters
    Example: get_addresses

  • moduleName    string

    The name of the module to which the permission belongs. This corresponds to the organizational section containing the permission when managing Company roles from the B2B Edition control panel.
    <= 50 characters
    Example: address

Example 1

{
"name": "Get addresses",
"description": "Get addresses",
"code": "get_addresses",
"moduleName": "address"
}

Response

OK

Body

object | application/json

  • code    integer

    Default: 200

  • data    object

  • meta    object

Example 1

{
"code": 200,
"data": {
"id": 1,
"name": "Get addresses",
"description": "Get addresses",
"code": "get_addresses",
"isCustom": false,
"moduleName": "address"
},
"meta": {
"message": "SUCCESS"
}
}

Delete Company Permission

DELETE /companies/permissions/{permissionId}

Request

Deletes a custom Company permission.

Predefined permissions cannot be deleted.

Authentication

  • authToken in header

Parameters

  • permissionId in path - integer
    required
    The unique identifier for a Company permission.

example

curl --request DELETE \
--url 'https://api-b2b.bigcommerce.com/api/v3/io/companies/permissions/[permissionId]' \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json

  • code    integer

  • data    object

  • meta    object

200 - SUCCESS

{
"code": 200,
"data": {},
"meta": {
"message": "SUCCESS"
}
}

Get Company Roles

GET /companies/roles

Request

Returns a list of Company user roles.

Authentication

  • authToken in header

Parameters

  • q in query - string
    Enter a Company role name to return partial and exact matches.
  • offset in query0 - integer
    The number of results to skip before returning the first result. If left blank, this defaults to 0.
  • limit in query with default of 10 - integer
    Determines the number of records to return per page. If left blank, this defaults to 10.

example

curl --request GET \
--url https://api-b2b.bigcommerce.com/api/v3/io/companies/roles \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json

  • code    integer

  • data    object

  • meta    object

Example 1

{
"code": 200,
"data": [
{
"id": 1,
"name": "io test",
"roleType": 2,
"roleLevel": 1
}
],
"meta": {
"message": "success",
"pagination": {
"totalCount": 1,
"limit": 10,
"offset": 0
}
}
}

Create a Company Role

POST /companies/roles

Request

Create a custom Company user role.

When adding predefined Company permissions to a user role, refer to Permission Codes for their name and code values.

Some permissions require prerequisites that must also be enabled in the role, and assigned to the same or higher permission level. See B2B Edition Buyer Roles and Permissions in the Help Center to learn more.

Authentication

  • authToken in header

Body

object | application/json

  • name    string
    required

    The name of the Company user role. This name is visible to system users and Company users.
    <= 200 characters
    Example: Sales Manager

  • permissions    array[object]
    required

Example 1

{
"name": "io test",
"permissions": [
{
"code": "get_addresses",
"permissionLevel": 2
}
]
}

Response

OK

Body

object | application/json

  • code    integer

  • data    object

  • meta    object

Example 1

{
"code": 200,
"data": {
"id": 1,
"name": "io test",
"roleType": 2,
"roleLevel": 1,
"permissions": [
{
"id": 1,
"code": "get_addresses",
"permissionLevel": 2
}
]
},
"meta": {
"message": "SUCCESS"
}
}

Get Company Role Details

GET /companies/roles/{roleId}

Request

Returns the details for a specific Company user role.

Authentication

  • authToken in header

Parameters

  • roleId in path - integer
    required
    The unique identifier for a Company user role.

example

curl --request GET \
--url 'https://api-b2b.bigcommerce.com/api/v3/io/companies/roles/[roleId]' \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json

  • code    integer

  • data    object

  • meta    object

Example 1

{
"code": 200,
"data": {
"id": 1,
"name": "io test",
"roleType": 2,
"roleLevel": 1,
"permissions": [
{
"id": 1,
"code": "get_addresses",
"permissionLevel": 2
}
]
},
"meta": {
"message": "SUCCESS"
}
}

Update Company Role

PUT /companies/roles/{roleId}

Request

Updates the name and permissions of a custom Company user role. You cannot update predefined roles.

When formatting the request body, you must add all permissions that you wish to keep in the role, including its existing permissions. See Permission Codes for a list of predefined permission name and code values.

Authentication

  • authToken in header

Parameters

  • roleId in path - integer
    required
    The unique identifier for a Company user role.

Body

object | application/json

  • name    string
    required

    The name of the Company user role. This name is visible to system users and Company users.
    <= 200 characters
    Example: Sales Manager

  • permissions    array[object]
    required

Example 1

{
"name": "io test",
"permissions": [
{
"code": "get_addresses",
"permissionLevel": 2
}
]
}

Response

OK

Body

object | application/json

  • code    integer

  • data    object

  • meta    object

Example 1

{
"code": 200,
"data": {
"id": 1,
"name": "Procurement Manager",
"roleType": 2,
"roleLevel": 1,
"permissions": [
{
"id": 1,
"code": "get_addresses",
"permissionLevel": 2
}
]
},
"meta": {
"message": "SUCCESS"
}
}

Delete a Company Role

DELETE /companies/roles/{roleId}

Request

Deletes a custom Company user role. You cannot delete predefined Company roles, or custom roles that are currently assigned to a Company user.

Authentication

  • authToken in header

Parameters

  • roleId in path - integer
    required
    The unique identifier for a Company user role.

example

curl --request DELETE \
--url 'https://api-b2b.bigcommerce.com/api/v3/io/companies/roles/[roleId]' \
--header 'Content-Type: application/json' \
--header 'authToken: {{token}}'

Response

OK

Body

object | application/json

  • code    integer

  • data    object

  • meta    object

200 - SUCCESS

{
"code": 200,
"data": {},
"meta": {
"message": "SUCCESS"
}
}
Did you find what you were looking for?
Delete a Company AttachmentGet All Company Permissions