Flux API Roles

Authentication: JWT | API Key

Flux API roles define what delivery endpoints a Flux API key can access. Each role contains read permissions for one or more Flux APIs, allowing you to isolate public endpoints or expose only selected APIs to a specific integration. Assign roles to Flux API keys when creating or updating the key.

Workflow Overview

  1. Create a Flux role – define a name/description for the delivery consumer.
  2. Grant delivery permissions – add a permission with content_type = "flux-apis" and actions = ["read"]. Decide whether all_objects should be true.
    • all_objects = true → the role can read every Flux API in the environment.
    • all_objects = false → the role requires explicit permission objects.
  3. Add permission objects (optional) – for all_objects=false, create object entries that point to individual Flux API key values from Manage Flux APIs. Each object unlocks a single Flux API prefix for that role.
  4. Assign the role to a Flux API key – when creating or updating a Flux API key, pass the role’s key. Delivery requests authenticated with that key inherit the role’s permissions.
  5. Iterate as needed – update or delete roles, permissions, or objects to adjust access. Removing a permission object immediately revokes access to that specific Flux API.

Keep this order in mind while following the reference below—the endpoints map directly to each step.

Path Parameters

  • Name
    :env
    Type
    string
    Description

    Unique identifier of the environment.

  • Name
    :role
    Type
    string
    Description

    Unique identifier of the Flux role.

All endpoints in this article live under /v1/:env/roles/flux-api/roles/….

Flux Role Object

  • Name
    key
    Type
    string
    Description

    Unique identifier for the role. Use this value when assigning the role to a Flux API key.

  • Name
    name
    Type
    string
    Description

    Role name shown in the dashboard and API responses.

  • Name
    description
    Type
    string
    Description

    Optional description of the role’s scope or intended consumers.

  • Name
    environment
    Type
    string
    Description

    Key of the environment the role belongs to.

  • Name
    created_at
    Type
    datetime
    Description

    ISO 8601 timestamp when the role was created.

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

List Flux Roles

Retrieves all Flux API roles in the environment. Standard limit/offset pagination applies.

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 Flux roles.

    • permission_denied - insufficient permissions to perform this action

Request

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

Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "flux_role_writers",
            "name": "Content Delivery",
            "description": "Used by partner writers",
            "environment": "7c9h4pwu",
            "created_at": "2024-01-15T10:30:00Z"
        }
    ]
}
POSTapi.foxnose.net/v1/:env/roles/flux-api/roles/

Create Flux Role

Creates a Flux API role for the current 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
    Description

    Optional description

    • Maximum length: 255

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 create Flux 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_flux_roles - environment reached the Flux role limit

Request

POST
/v1/:env/roles/flux-api/roles/
curl https://api.foxnose.net/v1/7c9h4pwu/roles/flux-api/roles/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "name": "Blog Readers",
    "description": "Read access to the blog delivery API"
}'

Response

{
    "key": "flux_role_blog_readers",
    "name": "Blog Readers",
    "description": "Read access to the blog delivery API",
    "environment": "7c9h4pwu",
    "created_at": "2024-01-15T10:45:00Z"
}
GETapi.foxnose.net/v1/:env/roles/flux-api/roles/:role/

Retrieve Flux Role

Retrieves the specified role.

Success Response: 200 OK

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 Flux roles.

    • permission_denied - insufficient permissions to perform this action
  • Name
    404 Not Found
    Description

    Role not found in the environment.

    • role_not_found - the specified role does not exist

Request

GET
/v1/:env/roles/flux-api/roles/:role/
curl https://api.foxnose.net/v1/7c9h4pwu/roles/flux-api/roles/flux_role_blog_readers/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "key": "flux_role_blog_readers",
    "name": "Blog Readers",
    "description": "Read access to the blog delivery API",
    "environment": "7c9h4pwu",
    "created_at": "2024-01-15T10:45:00Z"
}
PUTapi.foxnose.net/v1/:env/roles/flux-api/roles/:role/

Update Flux Role

Updates the role’s name or description.

Success Response: 200 OK

Request Body

  • Name
    name
    Type
    string
    Required
    required
    Description

    Updated role name.

  • Name
    description
    Type
    string
    Description

    Updated description.

Errors

  • Name
    401 Unauthorized
    Description

    Missing or invalid credentials.

  • Name
    403 Forbidden
    Description

    Caller lacks permission to update Flux roles.

    • permission_denied - insufficient permissions to perform this action
  • Name
    404 Not Found
    Description

    Role not found.

    • role_not_found - the specified role does not exist
  • Name
    422 Unprocessable Content
    Description

    Validation failed.

    • validation_error - request body failed validation

Request

PUT
/v1/:env/roles/flux-api/roles/:role/
curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/roles/flux-api/roles/flux_role_blog_readers/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "name": "Blog Delivery Readers",
    "description": "Access to the blog Flux API"
}'

Response

{
    "key": "flux_role_blog_readers",
    "name": "Blog Delivery Readers",
    "description": "Access to the blog Flux API",
    "environment": "7c9h4pwu",
    "created_at": "2024-01-15T10:45:00Z"
}
DELETEapi.foxnose.net/v1/:env/roles/flux-api/roles/:role/

Delete Flux Role

Deletes the role and its permissions.

Success Response: 204 No Content

Errors

  • Name
    401 Unauthorized
    Description

    Missing or invalid credentials.

  • Name
    403 Forbidden
    Description

    Caller lacks permission to delete Flux roles.

    • permission_denied - insufficient permissions to perform this action
  • Name
    404 Not Found
    Description

    Role not found.

    • role_not_found - the specified role does not exist

Request

DELETE
/v1/:env/roles/flux-api/roles/:role/
curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/roles/flux-api/roles/flux_role_blog_readers/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Manage Role Permissions

Flux roles grant read-only delivery access. Each role can include one permission with content_type = "flux-apis" and actions = ["read"]. Use all_objects=true to expose every Flux API in the environment, or keep it false and attach specific API keys via permission objects.

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

List Role Permissions

Returns all permissions attached 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 Flux roles.

  • Name
    404 Not Found
    Description

    Role not found.

    • role_not_found - the specified role does not exist

Request

GET
/v1/:env/roles/flux-api/roles/:role/permissions/
curl https://api.foxnose.net/v1/7c9h4pwu/roles/flux-api/roles/flux_role_blog_readers/permissions/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

[
    {
        "content_type": "flux-apis",
        "actions": ["read"],
        "all_objects": true
    }
]
POSTapi.foxnose.net/v1/:env/roles/flux-api/roles/:role/permissions/

Create or Update Role Permission

Adds or updates the delivery permission for the role. The API upserts the permission for the provided content_type.

Success Response: 201 Created

Request Body

  • Name
    content_type
    Type
    string
    Required
    required
    Description

    Must be "flux-apis".

  • Name
    actions
    Type
    array
    Required
    required
    Description

    Allowed actions for the content type. For Flux APIs, only ["read"] is valid.

  • Name
    all_objects
    Type
    boolean
    Default
    default:false
    Description
    • true – role can read every Flux API in the environment.
    • false – add specific API keys through permission objects.

    Switching all_objects to true ignores existing permission objects but does not delete them. When you later set all_objects=false, any previously stored objects become active again.

Errors

  • Name
    401 Unauthorized
    Description

    Missing or invalid credentials.

  • Name
    403 Forbidden
    Description

    Caller lacks permission to modify Flux roles.

  • Name
    404 Not Found
    Description

    Role not found.

  • Name
    422 Unprocessable Content
    Description

    Validation error.

    • validation_error - invalid content type or action

Request

POST
/v1/:env/roles/flux-api/roles/:role/permissions/
curl https://api.foxnose.net/v1/7c9h4pwu/roles/flux-api/roles/flux_role_blog_readers/permissions/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    \"content_type\": \"flux-apis\",
    \"actions\": [\"read\"],
    \"all_objects\": false
}'

Response

{
    "content_type": "flux-apis",
    "actions": ["read"],
    "all_objects": false
}
DELETEapi.foxnose.net/v1/:env/roles/flux-api/roles/:role/permissions/

Delete Role Permission

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

Success Response: 204 No Content

Query Parameters

  • Name
    content_type
    Type
    string
    Required
    required
    Description

    Set to flux-apis to delete the delivery permission.

Errors

  • Name
    401 Unauthorized
    Description

    Missing or invalid credentials.

  • Name
    403 Forbidden
    Description

    Caller lacks permission to modify Flux roles.

  • Name
    404 Not Found
    Description

    Role or permission entry not found.

    • role_not_found - the specified role does not exist
    • permissions_not_found - no permission exists for the provided content type

Request

DELETE
/v1/:env/roles/flux-api/roles/:role/permissions/
curl -X DELETE 'https://api.foxnose.net/v1/7c9h4pwu/roles/flux-api/roles/flux_role_blog_readers/permissions/?content_type=flux-apis' \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Flux Permission Objects

Use permission objects to limit a role to specific Flux APIs. Each object references a Flux API key (see Manage Flux APIs) and applies only when all_objects=false on the permission itself.

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

List Permission Objects

Lists Flux API keys that the role may access. Specify 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 flux-apis.

Errors

  • Name
    401 Unauthorized
    Description

    Missing or invalid credentials.

  • Name
    403 Forbidden
    Description

    Caller lacks permission to view Flux roles.

  • Name
    404 Not Found
    Description

    Role or permission entry not found.

    • permissions_not_found - the role does not have a permission for the provided content type

Request

GET
/v1/:env/roles/flux-api/roles/:role/permissions/objects/
curl 'https://api.foxnose.net/v1/7c9h4pwu/roles/flux-api/roles/flux_role_blog_readers/permissions/objects/?content_type=flux-apis' \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

[
    {
        "content_type": "flux-apis",
        "object_key": "dw2qC5qRwxuZ"
    }
]
POSTapi.foxnose.net/v1/:env/roles/flux-api/roles/:role/permissions/objects/

Add Permission Object

Adds a Flux API to the role’s permission scope.

Success Response: 201 Created

Request Body

  • Name
    content_type
    Type
    string
    Required
    required
    Description

    Must be flux-apis.

  • Name
    object_key
    Type
    string
    Required
    required
    Description

    Flux API key from Manage Flux APIs.

Errors

  • Name
    401 Unauthorized
    Description

    Missing or invalid credentials.

  • Name
    403 Forbidden
    Description

    Caller lacks permission to modify Flux roles.

  • Name
    404 Not Found
    Description

    Permission entry not found or API key does not exist.

    • permissions_not_found - the role does not have a matching permission
    • permission_object_not_found - referenced API key does not exist
  • Name
    422 Unprocessable Content
    Description

    Validation error.

    • permission_object_already_added - the API key is already linked
    • maximum_permissions_limit_exceeded - too many object-level entries

Request

POST
/v1/:env/roles/flux-api/roles/:role/permissions/objects/
curl https://api.foxnose.net/v1/7c9h4pwu/roles/flux-api/roles/flux_role_blog_readers/permissions/objects/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "content_type": "flux-apis",
    "object_key": "dw2qC5qRwxuZ"
}'
DELETEapi.foxnose.net/v1/:env/roles/flux-api/roles/:role/permissions/objects/

Remove Permission Object

Removes a specific Flux API from the role’s permission scope.

Success Response: 204 No Content

Request Body

  • Name
    content_type
    Type
    string
    Required
    required
    Description

    Must be flux-apis.

  • Name
    object_key
    Type
    string
    Required
    required
    Description

    Flux API key to remove.

Errors

  • Name
    401 Unauthorized
    Description

    Missing or invalid credentials.

  • Name
    403 Forbidden
    Description

    Caller lacks permission to modify Flux roles.

  • Name
    404 Not Found
    Description

    Permission or object entry not found.

    • permissions_not_found - the role does not have a matching permission
    • permission_object_not_found - the API key is not linked to this permission

Request

DELETE
/v1/:env/roles/flux-api/roles/:role/permissions/objects/
curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/roles/flux-api/roles/flux_role_blog_readers/permissions/objects/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "content_type": "flux-apis",
    "object_key": "dw2qC5qRwxuZ"
}'

Was this page helpful?