Request

Endpoint

Environment	HTTP Method	Endpoint
Sandbox testing	PUT	https://api-sandbox.flexfactor.io/v1/api-keys/{id}
Production environment	PUT	https://api.flexfactor.io/v1/api-keys/{id}

Required Key

Field	Description
`id`	The unique identifier of the API key to be updated or rotated.
`bearer token`	The authentication token returned by `/oauth2/token` for authorizing the API request.

Request Body

The request payload should include only the fields to be updated. To rotate the key, include the rotate field set to true.

Field Name	Field Type	Required	Description
`name`	String	No	A brief name or description of the API key. Regex: `^[^<>]*$`.
`scopes`	Array of Strings	No	List of scopes to define the access for this API key. Use `['*']` for all scopes except restricted ones.
`rotate`	Boolean	No	Set to `true` to rotate the key and generate a new key value. Defaults to `false`.

Available Scopes

The following scopes define access permissions for the API key. These are used to limit the key's operations:

General Access: api_keys:read, api_keys:write
Customer Management: customers:read, customers:write
Transactions: charges:read, refunds:read, refunds:write
Files and Reports: files:read, files:write, report_runs:read, report_runs:write
Onboarding: onboarding:read, onboarding:write
Webhooks: webhook_endpoints:read, webhook_endpoints:write

Response

Field Definitions

Field Name	Field Type	Field Explanation
`name`	String	The updated name or description of the API key.
`scopes`	Array of Strings	The updated list of scopes for the API key.
`rotatedValue`	String	The new API key value (only returned if the key is rotated).
`updatedFields`	Array of Strings	List of fields that were successfully updated.
`errors`	Array of Objects	Any validation errors or issues encountered during the update process.

❕
Important Notes

Rotating a Key: If rotate is set to true, a new key value will be generated, and the previous key will no longer be valid.

Key Security: The new key value is only returned upon rotation. Ensure it is stored securely, as it cannot be retrieved later.

Partial Updates: Only the specified fields in the request body will be updated; others will remain unchanged.

Validation Errors: Validation errors for fields will not affect the successful update of other fields.

Example Payloads

Request

cURL Request Example (Update Only)

curl --request PUT \
     --url https://api-sandbox.flexfactor.io/v1/api-keys/key_123456 \
     --header 'Authorization: Bearer {the token returned by /oauth2}' \
     --header 'Content-Type: application/json' \
     --data '{
       "name": "Updated API Key Name",
       "scopes": ["customers:read", "charges:read"]
     }'

cURL Request Example (Rotate Key)

curl --request PUT \
     --url https://api-sandbox.flexfactor.io/v1/api-keys/key_123456 \
     --header 'Authorization: Bearer {the token returned by /oauth2}' \
     --header 'Content-Type: application/json' \
     --data '{
       "rotate": true
     }'

Response

Example for a Successful Update

{
  "name": "Updated API Key Name",
  "scopes": ["customers:read", "charges:read"],
  "updatedFields": [
    "name",
    "scopes"
  ],
  "errors": []
}

Example for a Successful Rotation

{
  "name": "Updated API Key Name",
  "scopes": ["customers:read", "charges:read"],
  "rotatedValue": "sk_new_4eC39HqLyjWDarjtT1zdp7dc",
  "updatedFields": [
    "rotate"
  ],
  "errors": []
}

Example for an Update with Errors

{
  "name": "Updated API Key Name",
  "scopes": ["customers:read"],
  "updatedFields": [
    "name"
  ],
  "errors": [
    {
      "field": "scopes",
      "message": "Invalid scope value: 'invalid_scope'."
    }
  ]
}

Example for Handling Errors

Missing Required Parameters

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "errors": [
    {
      "field": "id",
      "message": "API key ID is required."
    }
  ]
}

Invalid Credentials

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errors": [
    "Authentication failed. Invalid bearer token."
  ]
}