API Clients endpoints (Client API: account)

19 FeatherPanel Client API: account endpoints from user/api-clients.php: methods, paths, auth, permissions, rate limits, parameters and responses.

Last synced from FeatherPanel 15b94e9 on 23 Oct 2026.

On this page

Defined in backend/app/routes/user/api-clients.php. Authentication used here: Signed-in user, Public. Read Authentication for how to send credentials and Rate limits and errors for the response envelope.

Paths, methods, permissions and rate limits come from the route file. Summaries, parameters and response codes come from the OpenAPI annotations on the controllers; endpoints without annotations show only what the route file declares.

Endpoints

GET`/api/user/api-clients`

Auth: Signed-in userRoute name: user-api-clientsController: ApiClientController::getApiClientsroute source

Get API clients Retrieve all API clients for the authenticated user with pagination and search functionality.

Parameter	In	Type	Required	Description
`page`	query	integer	no	Page number for pagination
`limit`	query	integer	no	Number of records per page
`search`	query	string	no	Search term to filter API clients by name

Response `data` field	Type	Description
`api_clients`	ApiClientList[]
`pagination`	ApiClientPagination
`search`	ApiClientSearch

curl -X GET "$PANEL_URL/api/user/api-clients" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 API clients retrieved successfully · 400 Bad request - Invalid authentication token · 401 Unauthorized - User not authenticated · 500 Internal server error - Failed to retrieve API clients

POST`/api/user/api-clients`

Auth: Signed-in userDefault rate limit: 10 / minute (user-api-clients)Route name: user-api-client-createController: ApiClientController::createApiClientroute source

Create API client Create a new API client for the authenticated user with automatically generated public and private keys.

Request body: ApiClientCreateRequest (application/json) · Response data: ApiClient

Body field	Type	Required	Description
`name`	string	yes	API client name
`allowed_ips`	string	no	Allowed IPs/CIDR (newline or comma); omit or empty for no restriction
`notify_foreign_ip`	boolean	no	Email when the key is used from a non-allowed IP (requires allowed_ips)

Response `data` field	Type	Description
`id`	integer	API client ID
`user_uuid`	string	User UUID
`name`	string	API client name
`public_key`	string	Public API key
`private_key`	string	Private API key (only shown on creation)
`created_at`	string (date-time)	Creation timestamp
`updated_at`	string (date-time)	Last update timestamp
`allowed_ips`	string	Allowed client IPs/CIDR (newline or comma separated); empty = no restriction
`notify_foreign_ip`	string	Email owner when a non-allowed IP attempts to use this key

curl -X POST "$PANEL_URL/api/user/api-clients" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","allowed_ips":"","notify_foreign_ip":false}'

Plugin events: featherpanel:user:api_client:created

Responses: 201 API client created successfully · 400 Bad request - Invalid authentication token, missing required fields, or invalid name length · 401 Unauthorized - User not authenticated · 500 Internal server error - Failed to create API client

POST`/api/user/api-clients/calagopus/create`

Auth: Signed-in userDefault rate limit: 10 / minute (user-api-clients)Route name: user-api-client-calagopus-createController: ApiClientController::calagopusCreateroute source

curl -X POST "$PANEL_URL/api/user/api-clients/calagopus/create" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

GET`/api/user/api-clients/calagopus/find`

Auth: Signed-in userDefault rate limit: 30 / minute (user-api-clients)Route name: user-api-client-calagopus-findController: ApiClientController::calagopusFindByKeyStartroute source

curl -X GET "$PANEL_URL/api/user/api-clients/calagopus/find" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

POST`/api/user/api-clients/calagopus/update-permissions`

Auth: Signed-in userDefault rate limit: 20 / minute (user-api-clients)Route name: user-api-client-calagopus-update-permissionsController: ApiClientController::calagopusUpdatePermissionsroute source

curl -X POST "$PANEL_URL/api/user/api-clients/calagopus/update-permissions" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

GET`/api/user/api-clients/{id}`

Auth: Signed-in userRoute name: user-api-client-getController: ApiClientController::getApiClientroute source

Get specific API client Retrieve details of a specific API client by ID for the authenticated user.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	API client ID

Response data: ApiClient

Response `data` field	Type	Description
`id`	integer	API client ID
`user_uuid`	string	User UUID
`name`	string	API client name
`public_key`	string	Public API key
`private_key`	string	Private API key (only shown on creation)
`created_at`	string (date-time)	Creation timestamp
`updated_at`	string (date-time)	Last update timestamp
`allowed_ips`	string	Allowed client IPs/CIDR (newline or comma separated); empty = no restriction
`notify_foreign_ip`	string	Email owner when a non-allowed IP attempts to use this key

curl -X GET "$PANEL_URL/api/user/api-clients/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 API client retrieved successfully · 400 Bad request - Invalid authentication token or API client ID · 401 Unauthorized - User not authenticated · 403 Forbidden - Access denied to API client · 404 Not found - API client not found · 500 Internal server error - Failed to retrieve API client

PUT`/api/user/api-clients/{id}`

Auth: Signed-in userDefault rate limit: 10 / minute (user-api-clients)Route name: user-api-client-updateController: ApiClientController::updateApiClientroute source

Update API client Update an existing API client for the authenticated user (name, allowed IPs/CIDR list, email alert for off-list IPs).

Parameter	In	Type	Required	Description
`id`	path	integer	yes	API client ID

Request body: ApiClientUpdateRequest (application/json) · Response data: ApiClient

Body field	Type	Required	Description
`name`	string	no	API client name
`allowed_ips`	string	no	Allowed IPs/CIDR; empty/null clears restriction
`notify_foreign_ip`	boolean	no	Email when the key is used from a off-list IP

Response `data` field	Type	Description
`id`	integer	API client ID
`user_uuid`	string	User UUID
`name`	string	API client name
`public_key`	string	Public API key
`private_key`	string	Private API key (only shown on creation)
`created_at`	string (date-time)	Creation timestamp
`updated_at`	string (date-time)	Last update timestamp
`allowed_ips`	string	Allowed client IPs/CIDR (newline or comma separated); empty = no restriction
`notify_foreign_ip`	string	Email owner when a non-allowed IP attempts to use this key

curl -X PUT "$PANEL_URL/api/user/api-clients/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"","allowed_ips":"","notify_foreign_ip":false}'

Plugin events: featherpanel:user:api_client:updated

Responses: 200 API client updated successfully · 400 Bad request - Invalid authentication token, API client ID, request data, or invalid name length · 401 Unauthorized - User not authenticated · 403 Forbidden - Access denied to API client · 404 Not found - API client not found · 500 Internal server error - Failed to update API client

DELETE`/api/user/api-clients/{id}`

Auth: Signed-in userDefault rate limit: 10 / minute (user-api-clients)Route name: user-api-client-deleteController: ApiClientController::deleteApiClientroute source

Delete API client Delete an API client for the authenticated user. This is a hard delete operation.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	API client ID

Response `data` field	Type	Description
`message`	string	Success message

curl -X DELETE "$PANEL_URL/api/user/api-clients/$ID" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:user:api_client:deleted

Responses: 200 API client deleted successfully · 400 Bad request - Invalid authentication token or API client ID · 401 Unauthorized - User not authenticated · 403 Forbidden - Access denied to API client · 404 Not found - API client not found · 500 Internal server error - Failed to delete API client

POST`/api/user/api-clients/{id}/regenerate`

Auth: Signed-in userDefault rate limit: 5 / minute (user-api-clients)Route name: user-api-client-regenerate-keysController: ApiClientController::regenerateApiKeysroute source

Regenerate API keys Regenerate both public and private API keys for an existing API client.

Parameter	In	Type	Required	Description
`id`	path	integer	yes	API client ID

Response data: ApiClient

Response `data` field	Type	Description
`id`	integer	API client ID
`user_uuid`	string	User UUID
`name`	string	API client name
`public_key`	string	Public API key
`private_key`	string	Private API key (only shown on creation)
`created_at`	string (date-time)	Creation timestamp
`updated_at`	string (date-time)	Last update timestamp
`allowed_ips`	string	Allowed client IPs/CIDR (newline or comma separated); empty = no restriction
`notify_foreign_ip`	string	Email owner when a non-allowed IP attempts to use this key

curl -X POST "$PANEL_URL/api/user/api-clients/$ID/regenerate" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Plugin events: featherpanel:user:api_client:updated

Responses: 200 API keys regenerated successfully · 400 Bad request - Invalid authentication token or API client ID · 401 Unauthorized - User not authenticated · 403 Forbidden - Access denied to API client · 404 Not found - API client not found · 500 Internal server error - Failed to regenerate API keys

GET`/api/user/api-clients/activities`

Auth: Signed-in userDefault rate limit: 30 / minute (user-api-clients)Route name: user-api-client-activitiesController: ApiClientController::getApiClientActivitiesroute source

Get API client activities Retrieve API client related activities for the authenticated user with pagination.

Parameter	In	Type	Required	Description
`page`	query	integer	no	Page number for pagination
`limit`	query	integer	no	Number of records per page

Response `data` field	Type	Description
`activities`	ApiClientActivity[]
`pagination`	ApiClientPagination

curl -X GET "$PANEL_URL/api/user/api-clients/activities" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 API client activities retrieved successfully · 400 Bad request - Invalid authentication token · 401 Unauthorized - User not authenticated · 500 Internal server error - Failed to retrieve activities

POST`/api/user/api-clients/validate`

Auth: PublicDefault rate limit: 10 / minute (user-api-clients-validate)Route name: user-api-client-validateController: ApiClientController::validateApiClientroute source

Validate API client Validate an API client by public key. This endpoint does not require authentication and only reports whether the key belongs to a valid API client (`valid`); no owner data is returned (FP-19).

Request body: ApiClientValidationRequest (application/json) · Response data: ApiClientValidationResponse

Body field	Type	Required	Description
`public_key`	string	yes	Public API key to validate

Response `data` field	Type	Description
`valid`	boolean	Whether the API client is valid

curl -X POST "$PANEL_URL/api/user/api-clients/validate" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"public_key":""}'

Responses: 200 API client validated successfully · 400 Bad request - Missing or empty public key · 404 Not found - Invalid API client or user not found · 500 Internal server error - Failed to validate API client

GET`/api/user/api-clients/oauth2/metadata`

Auth: Signed-in userDefault rate limit: 30 / minute (user-api-clients-oauth2)Route name: user-api-client-oauth2-metadataController: ApiClientController::oauth2Metadataroute source

Validate OAuth2 API consent request metadata Validates OAuth2 request query parameters and returns normalized request metadata without creating a pending grant.

curl -X GET "$PANEL_URL/api/user/api-clients/oauth2/metadata" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Metadata validated successfully · 400 Invalid request data · 403 Feature disabled for account

GET`/api/user/api-clients/oauth2/authorize`

Auth: Signed-in userDefault rate limit: 30 / minute (user-api-clients-oauth2)Route name: user-api-client-oauth2-authorizeController: ApiClientController::oauth2Authorizeroute source

Prepare OAuth2 API consent payload Validates an OAuth2-style API key authorization request and returns a normalized payload for consent UI.

curl -X GET "$PANEL_URL/api/user/api-clients/oauth2/authorize" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Authorization payload prepared successfully · 400 Invalid request data · 403 Feature disabled for account

POST`/api/user/api-clients/oauth2/authorize/approve`

Auth: Signed-in userDefault rate limit: 30 / minute (user-api-clients-oauth2)Route name: user-api-client-oauth2-approveController: ApiClientController::oauth2Approveroute source

Approve OAuth2 API authorization request Approves a pending OAuth2 API authorization request, creates API credentials, and returns callback redirect URL.

curl -X POST "$PANEL_URL/api/user/api-clients/oauth2/authorize/approve" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Authorization approved · 400 Invalid request token · 403 Unauthorized request

POST`/api/user/api-clients/oauth2/authorize/deny`

Auth: Signed-in userDefault rate limit: 30 / minute (user-api-clients-oauth2)Route name: user-api-client-oauth2-denyController: ApiClientController::oauth2Denyroute source

Deny OAuth2 API authorization request Denies a pending OAuth2 API authorization request and returns callback redirect URL with access_denied error.

curl -X POST "$PANEL_URL/api/user/api-clients/oauth2/authorize/deny" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Authorization denied · 400 Invalid request token · 403 Unauthorized request

POST`/api/user/api-clients/oauth2/token`

Auth: PublicDefault rate limit: 30 / minute (user-api-clients-oauth2)Route name: user-api-client-oauth2-tokenController: ApiClientController::oauth2Tokenroute source

Exchange OAuth2 authorization code Returns stored OAuth2 authorization metadata for approved requests. Use only for server-to-server integrations.

curl -X POST "$PANEL_URL/api/user/api-clients/oauth2/token" \
  -H "Accept: application/json"

Responses: 200 Token exchanged · 400 Invalid code

POST`/api/user/api-clients/oauth2/device`

Auth: PublicDefault rate limit: 10 / minute (user-api-clients-oauth2-device)Route name: user-api-client-oauth2-deviceController: ApiClientController::oauth2DeviceStartroute source

Start OAuth2 device authorization Starts a serverless/device-code OAuth2 API consent grant that does not require a callback URL. The client polls /oauth2/device/token while the user visits the verification URI.

curl -X POST "$PANEL_URL/api/user/api-clients/oauth2/device" \
  -H "Accept: application/json"

Responses: 200 Device authorization started · 400 Invalid request data

POST`/api/user/api-clients/oauth2/device/token`

Auth: PublicDefault rate limit: 20 / minute (user-api-clients-oauth2-device)Route name: user-api-client-oauth2-device-tokenController: ApiClientController::oauth2DeviceTokenroute source

Poll OAuth2 device authorization Polls a device authorization grant until the user approves or denies, or the grant expires.

curl -X POST "$PANEL_URL/api/user/api-clients/oauth2/device/token" \
  -H "Accept: application/json"

Responses: 200 Credentials issued or pending status · 400 Invalid or denied device code

GET`/api/user/api-clients/oauth2/device/claim`

Auth: Signed-in userDefault rate limit: 30 / minute (user-api-clients-oauth2-device)Route name: user-api-client-oauth2-device-claimController: ApiClientController::oauth2DeviceClaimroute source

Claim OAuth2 device authorization Binds a pending device authorization to the logged-in user and returns the consent payload.

curl -X GET "$PANEL_URL/api/user/api-clients/oauth2/device/claim" \
  -H "Authorization: Bearer $FEATHERPANEL_API_KEY" \
  -H "Accept: application/json"

Responses: 200 Device authorization claimed · 400 Invalid user code · 403 Feature disabled for account

API Clients endpoints (Client API: account)

Endpoints

GET/api/user/api-clients

POST/api/user/api-clients

POST/api/user/api-clients/calagopus/create

GET/api/user/api-clients/calagopus/find

POST/api/user/api-clients/calagopus/update-permissions

GET/api/user/api-clients/{id}

PUT/api/user/api-clients/{id}

DELETE/api/user/api-clients/{id}

POST/api/user/api-clients/{id}/regenerate

GET/api/user/api-clients/activities

POST/api/user/api-clients/validate

GET/api/user/api-clients/oauth2/metadata

GET/api/user/api-clients/oauth2/authorize

POST/api/user/api-clients/oauth2/authorize/approve

POST/api/user/api-clients/oauth2/authorize/deny

POST/api/user/api-clients/oauth2/token

POST/api/user/api-clients/oauth2/device

POST/api/user/api-clients/oauth2/device/token

GET/api/user/api-clients/oauth2/device/claim