Flux API Keys

Authentication: JWT | API Key

Flux API keys authenticate delivery traffic against your Flux APIs. Each key belongs to an environment and can inherit a Flux API Role, which grants exactly what its actions allow. A key with no role has no delivery access at all — a role is required before a key can do anything. See Authentication & access control for how Flux keys and roles secure content delivery.

A key’s full secret_key is returned only once at creation time. All subsequent responses include a masked value, and the service never stores the raw secret. Store the secret securely when you create the key.

A key can also carry an optional bearer token — an opaque fxk_ credential for hosted connectors that can only send Authorization: Bearer <token>. It is issued on request, never automatically, and follows the same show-once rule as secret_key.

Path Parameters

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

Endpoints live under /v1/:env/permissions/flux-api/api-keys/….

Flux API Key Object

Name
key
Type
string
Description
Internal identifier for the API key.
Name
description
Type
string
Description
Optional label (recommended max 100 characters).
Name
public_key
Type
string
Description
Public component of the API key. Use in the X-Fox-Public-Key header when calling Flux APIs.
Name
secret_key
Type
string
Description
Secret component of the key. Masked in all responses except the initial creation response.
Name
role
Type
string | null
Description
Flux role key assigned to this API key, or null if no role is assigned.
Name
environment
Type
string
Description
Key of the environment that owns the key.
Name
created_at
Type
datetime
Description
ISO 8601 timestamp when the key was created.
Name
bearer_token_prefix
Type
string | null
Description
First 12 characters of the key's bearer token (e.g. fxk_A7fQ2mXe), or null if none is issued. Enough to recognise a token in a config file or a log; never enough to use one.
Name
bearer_token_issued_at
Type
datetime | null
Description
When the current bearer token was issued, or null.

role: null does not mean unrestricted access — it means no delivery access at all. Requests made with a roleless key are denied with 403 access_denied on every Flux API. Assign a role with the actions you need (see Flux API Roles) before the key can do anything.

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

List Flux API Keys

Lists all Flux API keys in the environment. Supports 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 Flux API keys.
- permission_denied - insufficient permissions to perform this action

Request

GET

/v1/:env/permissions/flux-api/api-keys/

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

Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "key": "flux_key_v1",
            "description": "Blog delivery key",
            "public_key": "flux_pub_7Lx...",
            "secret_key": "flux_sec***********3kP",
            "role": "gq9kLm42",
            "environment": "7c9h4pwu",
            "created_at": "2024-01-15T10:50:00Z"
        }
    ]
}

POSTapi.foxnose.net/v1/:env/permissions/flux-api/api-keys/

Create Flux API Key

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

Success Response: 201 Created

Request Body

Name
description
Type
string
Default
default:''
Description
Optional label for the key
- Maximum length: 100
Name
role
Type
string | null
Default
default:null
Description
Optional Flux role key. Omitting the field or setting null creates a key with no delivery access — see the note above.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to create Flux 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 Flux role does not exist
Name
422 Unprocessable Content
Description
Validation or plan limit error.
- validation_error - request body failed validation
- too_many_flux_api_keys - environment reached its Flux API key limit

Request

POST

/v1/:env/permissions/flux-api/api-keys/

curl https://api.foxnose.net/v1/7c9h4pwu/permissions/flux-api/api-keys/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "description": "Blog delivery key",
    "role": "gq9kLm42"
}'

Response

{
    "key": "flux_key_v1",
    "description": "Blog delivery key",
    "public_key": "flux_pub_7LxXj8sYfH4Pn",
    "secret_key": "flux_sec_Jw9bSmcM4r5uTQ1g",
    "role": "gq9kLm42",
    "environment": "7c9h4pwu",
    "created_at": "2024-01-15T10:50:00Z"
}

Save both public_key and secret_key now. Once you close the response, the API cannot show the full secret again.

GETapi.foxnose.net/v1/:env/permissions/flux-api/api-keys/:apiKey/

Retrieve Flux API Key

Retrieves metadata for a specific key. The secret_key property is masked.

Success Response: 200 OK

Errors

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

Request

GET

/v1/:env/permissions/flux-api/api-keys/:apiKey/

curl https://api.foxnose.net/v1/7c9h4pwu/permissions/flux-api/api-keys/flux_key_v1/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
    "key": "flux_key_v1",
    "description": "Blog delivery key",
    "public_key": "flux_pub_7Lx...",
    "secret_key": "flux_sec***********3kP",
    "role": "gq9kLm42",
    "environment": "7c9h4pwu",
    "created_at": "2024-01-15T10:50:00Z"
}

PUTapi.foxnose.net/v1/:env/permissions/flux-api/api-keys/:apiKey/

Update Flux API Key

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

Success Response: 200 OK

Request Body

Name
description
Type
string
Default
default:''
Description
Updated label for the key
- Maximum length: 100
Name
role
Type
string | null
Description
Flux role key, or null to remove the role assignment. Setting it to null immediately strips the key of delivery access — see the note under the Flux API Key Object.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks permission to update Flux 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 - the role does not exist (when provided)
Name
422 Unprocessable Content
Description
Validation error.
- validation_error - request body failed validation

Request

PUT

/v1/:env/permissions/flux-api/api-keys/:apiKey/

curl -X PUT https://api.foxnose.net/v1/7c9h4pwu/permissions/flux-api/api-keys/flux_key_v1/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
-H "Content-Type: application/json" \
-d '{
    "description": "Partner blog key",
    "role": null
}'

Response

{
    "key": "flux_key_v1",
    "description": "Partner blog key",
    "public_key": "flux_pub_7Lx...",
    "secret_key": "flux_sec***********3kP",
    "role": null,
    "environment": "7c9h4pwu",
    "created_at": "2024-01-15T10:50:00Z"
}

DELETEapi.foxnose.net/v1/:env/permissions/flux-api/api-keys/:apiKey/

Delete Flux API Key

Deletes the key, removing every credential it carries — its public/private pair and its bearer token, if one was issued.

Both credentials stop working immediately in normal operation. Under a transient fault the change can take up to 5 minutes to reach everywhere, so treat a deleted key as revoked but verify before relying on it in a security incident.

Success Response: 204 No Content

Errors

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

Request

DELETE

/v1/:env/permissions/flux-api/api-keys/:apiKey/

curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/permissions/flux-api/api-keys/flux_key_v1/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

POSTapi.foxnose.net/v1/:env/permissions/flux-api/api-keys/:apiKey/bearer-token/

Bearer Token

Issues a bearer token for the key, or replaces the existing one. A key has at most one token, and no token until you ask for one.

The plaintext is returned once. Only a hash is stored, exactly as for secret_key — a lost token is re-issued, not recovered. The response is sent with Cache-Control: no-store.

Re-issuing does not touch the key. public_key, secret_key, role and grants are unchanged, so Simple and Secure integrations keep working across a rotation. That is what makes this the way to cut off a connector without recreating a key and reconfiguring everything that uses it.

Success Response: 200 OK

Response Fields

Name
bearer_token
Type
string
Description
The credential, e.g. fxk_A7fQ2mXe.... 47 characters, and contains no : — so it can never be confused with a public:private pair. Shown once.
Name
bearer_token_prefix
Type
string
Description
First 12 characters, also returned by every key read.
Name
bearer_token_issued_at
Type
datetime
Description
ISO 8601 issue timestamp.

Permissions

Issuing a token hands out a usable credential, which is what creating a key does — and what update deliberately does not, since changing a key's role never reveals a way to authenticate as it.

Name
First issuance
Description
Requires create on flux-api-keys.
Name
Re-issuing
Description
Requires create and update — it mints a credential and destroys a live one.

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks the permissions above.
Name
404 Not Found
Description
Key not found in the environment.

Request

POST

/v1/:env/permissions/flux-api/api-keys/:apiKey/bearer-token/

curl -X POST https://api.foxnose.net/v1/7c9h4pwu/permissions/flux-api/api-keys/flux_key_v1/bearer-token/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."

Response

{
  "bearer_token": "fxk_A7fQ2mXeKp3vR8sT1uW5yZ2bC6dF9gH0jL4nQ7x",
  "bearer_token_prefix": "fxk_A7fQ2mXe",
  "bearer_token_issued_at": "2026-08-09T10:24:11.482Z"
}

DELETEapi.foxnose.net/v1/:env/permissions/flux-api/api-keys/:apiKey/bearer-token/

Revoke Bearer Token

Revokes the key's bearer token. The key and its role keep working — only the token is removed, so Simple and Secure are unaffected.

Idempotent: 204 whether or not a token was issued.

The token stops working immediately in normal operation. As with key deletion, a transient fault can delay that by up to 5 minutes.

Requires update on flux-api-keys: revoking is purely a reduction, and requiring more would make a token harder to revoke than the whole key.

Success Response: 204 No Content

Errors

Name
401 Unauthorized
Description
Missing or invalid credentials.
Name
403 Forbidden
Description
Caller lacks update on Flux API keys.
Name
404 Not Found
Description
Key not found in the environment.

Request

DELETE

/v1/:env/permissions/flux-api/api-keys/:apiKey/bearer-token/

curl -X DELETE https://api.foxnose.net/v1/7c9h4pwu/permissions/flux-api/api-keys/flux_key_v1/bearer-token/ \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..."