> ## Documentation Index
> Fetch the complete documentation index at: https://broker-docs.newyorkcityservers.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Change Service Password
> Set or generate a new password for an eligible VPS service.
This request changes the service password that the client uses to access their VPS.
## Behavior
This endpoint is used for managing the remote desktop password for the VPS. This is the same password that the client uses to access their service.
A successful submission changes the service password immediately. From this point forward the old password will no longer work, and the client must use the new password to access their service.
You may use the "email\_client" parameter to send a new VPS welcome email to the client, which contains the new password.
## Errors
All error responses have `success: false` and an `error` object.
| HTTP status | Error code | Cause |
| ----------- | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| `400` | `invalid_parameter` | The service number is invalid, or the supplied password fails a password rule. |
| `400` | `invalid_request` | The body is not valid JSON, neither password mode is present, or both password modes are present. |
| `400` | `service_pending_provisioning` | The service is still pending provisioning. |
| `400` | `invalid_state` | The service is cancelled, terminated, missing an upstream service ID, or on a Dedicated Server plan. |
| `401` | `authentication_failed` | The API key is missing, invalid, inactive, or expired. |
| `403` | `insufficient_permissions` | The key does not have `admin:full`, or the request IP is not allowed. |
| `404` | `not_found` | No service with this number belongs to the authenticated broker. |
| `429` | `rate_limit_exceeded` | The API key has reached its rate limit. |
| `500` | `password_update_failed` | Virtualizor or WHMCS could not change the password. |
| `500` | `password_cache_update_failed` | The upstream password changed, but the local credential cache could not be updated. |
| `500` | `server_error` | The request could not complete. |
## OpenAPI
````yaml api/openapi.yaml POST /v1/services/{service_number}/password
openapi: 3.1.0
info:
title: Broker API
version: 1.0.0
description: API for broker-scoped service, request, and report operations.
servers:
- url: https://brokers.newyorkcityservers.com/api
description: Broker Panel API
security:
- bearerAuth: []
tags:
- name: Authentication
- name: Services
- name: Requests
- name: Reports
paths:
/v1/services/{service_number}/password:
post:
tags:
- Services
summary: Change Service Password
description: >-
Sets or generates a password for an eligible VPS and can resend its
welcome email. Requires `admin:full`.
operationId: changeServicePassword
parameters:
- $ref: '#/components/parameters/ServiceNumber'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PasswordChangeRequest'
examples:
supplied:
value:
new_password: ExampleSecurePass9
email_client: true
generated:
value:
generate_password: true
email_client: false
responses:
'200':
description: Password updated.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SuccessEnvelope'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PasswordChangeResult'
example:
success: true
data:
service_number: 30897
operation_status: password_updated
message: Service password updated successfully.
generated_password:
email_sent: true
'400':
description: >-
Codes `invalid_request`, `invalid_parameter`,
`service_pending_provisioning`, or `invalid_state`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidPassword:
value:
success: false
error:
code: invalid_parameter
message: >-
New password must be between 8 and 32 characters; must
contain at least one uppercase letter.
pendingService:
value:
success: false
error:
code: service_pending_provisioning
message: >-
Service is still pending provisioning and this action is
not available yet.
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/PermissionError'
'404':
description: Code `not_found` when no broker-owned service matches.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
error:
code: not_found
message: Service not found
'429':
$ref: '#/components/responses/RateLimitError'
'500':
description: >-
Codes `password_update_failed`, `password_cache_update_failed`, or
`server_error`.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
error:
code: password_cache_update_failed
message: >-
Password was updated, but the new credentials could not be
refreshed.
components:
parameters:
ServiceNumber:
name: service_number
in: path
required: true
description: Public service number parsed as a base-10 integer.
schema:
type: integer
format: int64
schemas:
PasswordChangeRequest:
type: object
description: >-
Provide either `new_password` or a true `generate_password` value, but
not both.
properties:
new_password:
type: string
minLength: 8
maxLength: 32
description: >-
Must have uppercase, lowercase, and numeric characters and no
surrounding whitespace.
generate_password:
type: boolean
default: false
email_client:
type: boolean
default: false
oneOf:
- required:
- new_password
properties:
generate_password:
const: false
- required:
- generate_password
properties:
generate_password:
const: true
not:
required:
- new_password
SuccessEnvelope:
type: object
required:
- success
properties:
success:
type: boolean
const: true
message:
type: string
pagination:
$ref: '#/components/schemas/Pagination'
PasswordChangeResult:
type: object
required:
- service_number
- operation_status
- message
properties:
service_number:
type: integer
operation_status:
type: string
const: password_updated
message:
type: string
const: Service password updated successfully.
generated_password:
type: string
email_sent:
type: boolean
warning:
type: string
ErrorResponse:
type: object
required:
- success
- error
properties:
success:
type: boolean
const: false
error:
$ref: '#/components/schemas/Error'
Pagination:
type: object
required:
- page
- perPage
- total
- totalPages
properties:
page:
type: integer
minimum: 1
perPage:
type: integer
minimum: 1
maximum: 100
total:
type: integer
minimum: 0
totalPages:
type: integer
minimum: 0
Error:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
details:
type: object
additionalProperties: true
responses:
AuthenticationError:
description: >-
Code `authentication_failed` for a missing, malformed, invalid,
inactive, or expired API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
error:
code: authentication_failed
message: Invalid API key
PermissionError:
description: >-
Code `insufficient_permissions` when the request IP is not whitelisted
or a required scope is missing.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
error:
code: insufficient_permissions
message: IP address not whitelisted
RateLimitError:
description: Code `rate_limit_exceeded` when the API key exceeds its rate limit.
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
minimum: 1
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
error:
code: rate_limit_exceeded
message: Rate limit exceeded
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: >-
Send the API key in the Authorization bearer header. Production keys
begin with `sk_live_`.
````