Management API Roles

Authentication: JWT | API Key

Management API roles control what workspace users and API keys can do inside an environment. Each role contains a set of permissions (create/read/update/delete) across specific scopes such as folders, resources, schemas, or access management. You can optionally mark a role as full access, which bypasses individual permission checks.

Path Parameters

Name
:env
Type
string
Description
Environment key that owns the roles.
Name
:role
Type
string
Description
Unique identifier of the management role (key field).

Management role endpoints live under /v1/:env/roles/management-api/roles/….

Role Object

Name
key
Type
string
Description
Short identifier for the role.
Name
name
Type
string
Description
Role name displayed in dashboards and API responses.
Name
description
Type
string
Description
Optional role description (max 255 characters).
Name
full_access
Type
boolean
Description
When true, the role bypasses permission checks and has unrestricted access to the environment.
Name
environment
Type
string
Description
Key of the environment that owns this role.
Name
created_at
Type
datetime
Description
ISO 8601 timestamp when the role was created.

Workflow Overview

Create a management role – define the name, description, and whether it should have full access.
Add permissions – specify the content_type, actions, and (optionally) object-level restrictions.
(Optional) Use batch updates – replace the entire permission set in a single request.
Assign the role – attach the role to users or Management API keys via the Access Control endpoints.
Iterate – update role metadata or permissions, or delete roles that are no longer needed.

GETapi.foxnose.net/v1/:env/roles/management-api/roles/

List Management Roles

Lists all management roles in the environment. Supports limit/offset pagination.

Success Response: 200 OK

Query Parameters

Name
limit
Type
integer
Default
default:100
Description
Number of roles per page.
Name
offset
Type
integer
Default
default:0
Description
Number of roles to skip before starting the page.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
- authentication_failed - authentication credentials were not provided or are invalid
Name
403 Forbidden
Description
Caller lacks permission to view management roles.
- permission_denied - insufficient permissions to perform this action

Request

GET

/v1/:env/roles/management-api/roles/

curl https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "env_role_admins",
            "name": "Workspace Admins",
            "description": "Full access for admins",
            "full_access": true,
            "environment": "7c9h4pwu",
            "created_at": "2024-01-20T09:00:00Z"
        }
    ]
}

POSTapi.foxnose.net/v1/:env/roles/management-api/roles/

Create Management Role

Creates a role in the specified environment.

Success Response: 201 Created

Request Body

Name
name
Type
string
Required
required
Description
Role name
- Minimum length: 1
- Maximum length: 100
Name
description
Type
string
Default
default:''
Description
Optional description
- Maximum length: 255
Name
full_access
Type
boolean
Default
default:false
Description
Set to true to grant unrestricted access without configuring permissions.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to create management roles.
- permission_denied - insufficient permissions to perform this action
Name
422 Unprocessable Content
Description
Validation or plan limit error.
- validation_error - request body failed validation
- too_many_manage_roles - environment reached the management role limit

Request

POST

/v1/:env/roles/management-api/roles/

curl https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "name": "Content Editors",
    "description": "Edit content but no access to schemas",
    "full_access": false
}'

Response

{
    "key": "env_role_editors",
    "name": "Content Editors",
    "description": "Edit content but no access to schemas",
    "full_access": false,
    "environment": "7c9h4pwu",
    "created_at": "2024-01-20T09:05:00Z"
}

GETapi.foxnose.net/v1/:env/roles/management-api/roles/:role/

Retrieve Management Role

Returns details of a single role.

Success Response: 200 OK

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to view management roles.
Name
404 Not Found
Description
Role not found.
- role_not_found - the specified role does not exist

Request

GET

/v1/:env/roles/management-api/roles/:role/

curl https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/env_role_editors/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "key": "env_role_editors",
    "name": "Content Editors",
    "description": "Edit content but no access to schemas",
    "full_access": false,
    "environment": "7c9h4pwu",
    "created_at": "2024-01-20T09:05:00Z"
}

PUTapi.foxnose.net/v1/:env/roles/management-api/roles/:role/

Update Management Role

Updates role metadata.

Success Response: 200 OK

Request Body

Name
name
Type
string
Required
required
Description
Updated role name (1–100 characters).
Name
description
Type
string
Default
default:''
Description
Updated description (max 255 characters).
Name
full_access
Type
boolean
Default
default:false
Description
Toggle full access for the role.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to update management roles.
Name
404 Not Found
Description
Role not found.
- role_not_found - the specified role does not exist
Name
422 Unprocessable Content
Description
Validation error.
- validation_error - request body failed validation

Request

PUT

/v1/:env/roles/management-api/roles/:role/

curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/env_role_editors/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "name": "Content Editors",
    "description": "Editors with restricted schema access",
    "full_access": false
}'

Response

{
    "key": "env_role_editors",
    "name": "Content Editors",
    "description": "Editors with restricted schema access",
    "full_access": false,
    "environment": "7c9h4pwu",
    "created_at": "2024-01-20T09:05:00Z"
}

DELETEapi.foxnose.net/v1/:env/roles/management-api/roles/:role/

Delete Management Role

Deletes a role and its permissions. Existing user/API key assignments referencing this role will lose access.

Success Response: 204 No Content

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to delete management roles.
Name
404 Not Found
Description
Role not found.
- role_not_found - the specified role does not exist

Request

DELETE

/v1/:env/roles/management-api/roles/:role/

curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/env_role_editors/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "content_type": "folder-items",
    "object_key": "folder_blog_posts"
}

Manage Permissions

Management roles support fine-grained permissions across multiple scopes. Valid content_type values and actions include:

env-settings – read, update
manage-api-roles, flux-api-roles, user-assignments, key-assignments, manage-api-keys, flux-api-keys, folder-structure, resources, management-apis, collection-schemas, components – create, read, update, delete
folder-items – read

Use all_objects=true to make the permission apply to every object for the given content type. When all_objects=false, add specific objects through permission objects.

GETapi.foxnose.net/v1/:env/roles/management-api/roles/:role/permissions/

List Role Permissions

Lists permissions assigned to the role.

Success Response: 200 OK

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to view management roles.
Name
404 Not Found
Description
Role not found.
- role_not_found - the specified role does not exist

Request

GET

/v1/:env/roles/management-api/roles/:role/permissions/

curl https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/env_role_editors/permissions/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

[
    {
        "content_type": "resources",
        "actions": ["read", "update"],
        "all_objects": true
    }
]

POSTapi.foxnose.net/v1/:env/roles/management-api/roles/:role/permissions/

Create or Update Role Permission

Adds or updates a permission for a specific content type. Sending the same content_type replaces the existing entry.

Success Response: 201 Created (new) or 200 OK (updated)

Request Body

Name
content_type
Type
string
Required
required
Description
One of the supported content types listed above.
Name
actions
Type
array
Required
required
Description
List of allowed actions for this content type.
Name
all_objects
Type
boolean
Default
default:true
Description
Whether the permission applies to all objects for the given content type.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to modify management roles.
Name
404 Not Found
Description
Role not found.
- role_not_found - the specified role does not exist
Name
422 Unprocessable Content
Description
Validation error.
- validation_error - invalid content type or action

Request

POST

/v1/:env/roles/management-api/roles/:role/permissions/

curl https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/env_role_editors/permissions/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "content_type": "resources",
    "actions": ["read", "update"],
    "all_objects": true
}'

Response

{
    "content_type": "resources",
    "actions": ["read", "update"],
    "all_objects": true
}

DELETEapi.foxnose.net/v1/:env/roles/management-api/roles/:role/permissions/

Delete Role Permission

Deletes the permission entry for the specified content type. Provide content_type as a query parameter.

Success Response: 204 No Content

Query Parameters

Name
content_type
Type
string
Required
required
Description
Content type to remove, e.g., resources.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to modify management roles.
Name
404 Not Found
Description
Role or permission not found.
- role_not_found - the specified role does not exist
- permissions_not_found - role does not have a permission for that content type

Request

DELETE

/v1/:env/roles/management-api/roles/:role/permissions/

curl -X DELETE 'https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/env_role_editors/permissions/?content_type=resources' \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

POSTapi.foxnose.net/v1/:env/roles/management-api/roles/:role/permissions/batch/

Batch Replace Permissions

Replaces the entire permission set in a single request. Provide an array of permission objects (same shape as the single-permission endpoint). The API removes any permissions not included in the array.

Success Response: 200 OK

Request Body

Name
[]
Type
array
Required
required
Description
Each entry matches the single-permission schema from Create or Update Role Permission.

[
    {"content_type": "resources", "actions": ["read", "update"], "all_objects": true},
    {"content_type": "folder-items", "actions": ["read"], "all_objects": false}
]

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to modify management roles.
Name
404 Not Found
Description
Role not found.
Name
422 Unprocessable Content
Description
Validation error in one or more permission entries.

Request

POST

/v1/:env/roles/management-api/roles/:role/permissions/batch/

curl https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/env_role_editors/permissions/batch/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '[{"content_type":"resources","actions":["read","update"],"all_objects":true}]'

Permission Objects

Use permission objects to restrict permissions that support object-level scoping. For management roles, only the folder-items content type is object-based. Each object key references a folder key, allowing the role to read only specific folders.

GETapi.foxnose.net/v1/:env/roles/management-api/roles/:role/permissions/objects/

List Permission Objects

Lists folder keys attached to the folder-items permission. Provide the permission’s content type via the content_type query parameter.

Success Response: 200 OK

Query Parameters

Name
content_type
Type
string
Required
required
Description
Must be folder-items.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to view management roles.
Name
404 Not Found
Description
Permission not found for the provided content type.
- permissions_not_found - role lacks a matching permission

Request

GET

/v1/:env/roles/management-api/roles/:role/permissions/objects/

curl 'https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/env_role_editors/permissions/objects/?content_type=folder-items' \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

[
    {
        "content_type": "folder-items",
         "object_key": "mK8nP3tY"
    }
]

POSTapi.foxnose.net/v1/:env/roles/management-api/roles/:role/permissions/objects/

Add Permission Object

Adds a folder key to the permission scope. The permission must already exist and have all_objects=false.

Success Response: 201 Created

Request Body

Name
content_type
Type
string
Required
required
Description
Must be folder-items.
Name
object_key
Type
string
Required
required
Description
Folder key to grant access to.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to modify management roles.
Name
404 Not Found
Description
Permission entry not found or folder does not exist.
- permissions_not_found - role lacks a matching permission
- permission_object_not_found - folder key does not exist
Name
422 Unprocessable Content
Description
Business rule error.
- not_object_based_permission - content type does not support objects
- permission_object_already_added - folder already linked
- maximum_permissions_limit_exceeded - too many object-level entries

Request

POST

/v1/:env/roles/management-api/roles/:role/permissions/objects/

curl https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/env_role_editors/permissions/objects/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "content_type": "folder-items",
    "object_key": "mK8nP3tY"
}'

DELETEapi.foxnose.net/v1/:env/roles/management-api/roles/:role/permissions/objects/

Remove Permission Object

Removes a folder from the permission scope.

Success Response: 204 No Content

Request Body

Name
content_type
Type
string
Required
required
Description
Must be folder-items.
Name
object_key
Type
string
Required
required
Description
Folder key to revoke access from.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to modify management roles.
Name
404 Not Found
Description
Permission or folder entry not found.
- permissions_not_found - role lacks a matching permission
- permission_object_not_found - folder not linked to this permission

Request

DELETE

/v1/:env/roles/management-api/roles/:role/permissions/objects/

curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/roles/env_role_editors/permissions/objects/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "content_type": "folder-items",
    "object_key": "mK8nP3tY"
}'