Management API Keys

Authentication: JWT | API Key

Management API keys authenticate requests that manage content models, resources, roles, and other administrative workflows. Each key belongs to an environment and may inherit a Management API Role. Roles determine what the key can do within the environment.

The service never stores full secret_key values. The complete secret is returned only in the creation response—store it securely, because later requests show a masked value.

Path Parameters

Name
:env
Type
string
Description
Environment key that owns the API keys.
Name
:apiKey
Type
string
Description
Unique identifier of the Management API key (key field).

Management API key endpoints live under /v1/:env/roles/management-api/api-keys/….

Management API Key Object

Name
key
Type
string
Description
Short identifier for the API key.
Name
description
Type
string
Description
Optional label (max 100 characters).
Name
public_key
Type
string
Description
Public component of the API key. Use in the X-Fox-Public-Key header.
Name
secret_key
Type
string
Description
Secret component of the key. Masked on retrieval.
Name
role
Type
string | null
Description
Management role key assigned to the key, or null for unrestricted access.
Name
environment
Type
string
Description
Environment key that owns the API key.
Name
created_at
Type
datetime
Description
ISO 8601 timestamp when the key was created.

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

List Management API Keys

Lists all Management API keys in the environment with standard limit/offset pagination.

Success Response: 200 OK

Query Parameters

Name
limit
Type
integer
Default
default:100
Description
Number of keys per page.
Name
offset
Type
integer
Default
default:0
Description
Number of keys 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 API keys.
- permission_denied - insufficient permissions to perform this action

Request

GET

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

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

Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "env_key_71s",
            "description": "CI automation key",
            "public_key": "manage_pub_AVx...",
            "secret_key": "manage_sec***********4Nx",
            "role": "env_role_admins",
            "environment": "7c9h4pwu",
            "created_at": "2024-01-15T08:00:00Z"
        }
    ]
}

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

Create Management API Key

Generates a new Management API key and returns the full credentials once.

Success Response: 201 Created

Request Body

Name
description
Type
string
Default
default:''
Description
Optional label
- Maximum length: 100
Name
role
Type
string | null
Default
default:null
Description
Optional management role key. Omit or set null to create an unrestricted key.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to create Management API keys.
- permission_denied - insufficient permissions to perform this action
Name
404 Not Found
Description
Role not found (when role is provided).
- role_not_found - specified management role does not exist
Name
422 Unprocessable Content
Description
Validation or plan limit error.
- validation_error - request body failed validation
- too_many_manage_api_keys - environment reached the API key limit

Request

POST

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

curl https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/api-keys/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "description": "CI automation key",
    "role": "env_role_admins"
}'

Response

{
    "key": "env_key_71s",
    "description": "CI automation key",
    "public_key": "manage_pub_AVx8bmd3LkP",
    "secret_key": "manage_sec_Jw9bSmcM4r5uTQ1g",
    "role": "env_role_admins",
    "environment": "7c9h4pwu",
    "created_at": "2024-01-15T08:00:00Z"
}

Save both public_key and secret_key now—they cannot be retrieved again after this response.

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

Retrieve Management API Key

Retrieves metadata for a specific key (with masked secret).

Success Response: 200 OK

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to view Management API keys.
Name
404 Not Found
Description
Key not found.
- api_key_not_found - the specified key does not exist

Request

GET

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

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

Response

{
    "key": "env_key_71s",
    "description": "CI automation key",
    "public_key": "manage_pub_AVx...",
    "secret_key": "manage_sec***********4Nx",
    "role": "env_role_admins",
    "environment": "7c9h4pwu",
    "created_at": "2024-01-15T08:00:00Z"
}

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

Update Management API Key

Updates the key’s description and/or role assignment.

Success Response: 200 OK

Request Body

Name
description
Type
string
Default
default:''
Description
Updated label (max 100 characters).
Name
role
Type
string | null
Default
default:null
Description
Management role key to assign, or null to remove the role.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to update Management API keys.
Name
404 Not Found
Description
Key or role not found.
- api_key_not_found - the specified key does not exist
- role_not_found - provided role does not exist
Name
422 Unprocessable Content
Description
Validation error.
- validation_error - request body failed validation

Request

PUT

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

curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/roles/management-api/api-keys/env_key_71s/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "description": "CI automation key (rotated)",
    "role": null
}'

Response

{
    "key": "env_key_71s",
    "description": "CI automation key (rotated)",
    "public_key": "manage_pub_AVx...",
    "secret_key": "manage_sec***********4Nx",
    "role": null,
    "environment": "7c9h4pwu",
    "created_at": "2024-01-15T08:00:00Z"
}

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

Delete Management API Key

Deletes the key and removes role associations. Deletion immediately revokes 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 API keys.
Name
404 Not Found
Description
Key not found.
- api_key_not_found - the specified key does not exist

Request

DELETE

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

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