> ## Documentation Index > Fetch the complete documentation index at: https://docs.rightfoot.com/llms.txt > Use this file to discover all available pages before exploring further. # Update a Processor Key > Rename a key, change its payment types, make it the default, or replace the key itself # Update a Processor Key Send only the fields you want to change. At least one is required. | Field | What it does | | ------------ | ------------------------------------------------------------------------------------ | | `label` | Renames the key | | `rail_scope` | Changes which payment types it can take | | `is_default` | `true` makes it the default for its `rail_scope`; `false` stops it being the default | | `api_key` | Replaces the stored key. The previous one is revoked once the new one is stored | `merchant_ref` is not accepted — see [Tags cannot change](#tags-cannot-change). ## Make a key the default Promoting a key (`is_default: true`) swaps it with the current default for the same `rail_scope`, if there is one. That key becomes an ordinary untagged key; nothing else about it changes. Only untagged keys can be promoted. A tagged key is reached by naming its tag, and making it the default would send untagged borrowers to a merchant account you set aside for tagged ones — the request is rejected with `400`. To serve borrowers enrolled without a tag, add or promote an untagged key. Demoting (`is_default: false`) needs no replacement. A payment type the demoted key covered falls back to a default `both` key if you have one; only when no other default covers it are borrowers enrolled without a tag skipped on that type, until you set a new default — `GET /v1/payment_connections` shows any gap in `missing_default_rails`. ## Replace a key To rotate credentials, send the new `api_key` on its own. The label, tag and payment types stay as they are, `key_last4` changes, and the previous key is revoked as soon as the new one is stored. If the new key cannot be stored, the previous one stays in place. Replacing the key is also how you move a tag to a different merchant account: swap in that account's key and every borrower enrolled under the tag follows. ## Tags cannot change `merchant_ref` is fixed when the key is added. Borrowers already enrolled under a tag would silently move to a different merchant account if it could change, so a request that includes `merchant_ref` is rejected with `400`. ## When a request is rejected | Status | When | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Nothing to change, `merchant_ref` was sent, or a tagged key was promoted | | `404` | No key with this `id` for your account | | `409` | Moving a default key onto a `rail_scope` that already has a default, or moving a tagged key onto a `rail_scope` its tag already has a key for | ## OpenAPI ````yaml PATCH /v1/payment_connections/{id} openapi: 3.1.0 info: title: Rightfoot API description: >- Submit a batch of authorizers for balance checks, retrieve processed balances, and check the status of a batch. version: 0.3.0-alpha servers: - url: https://api.rightfoot.com security: - BearerAuth: [] tags: - name: General Availability description: | **General Availability** indicates that the endpoint is production-ready. - name: Early Access description: > **Early Access** indicates that the endpoint is available for early access customers and is being actively refined. - name: In Development description: > **In Development** indicates that the endpoint is currently being built and will be available in an upcoming release. paths: /v1/payment_connections/{id}: patch: tags: - In Development summary: Update a processor key description: > Rename a key, change the payment types it can take, make it the default or stop it being the default, or replace the key itself. Send only the fields you want to change; at least one is required. `merchant_ref` cannot be changed. Borrowers already enrolled under a tag would silently move to a different merchant account if it could, so a request that includes `merchant_ref` is rejected with `400`. **Promoting** (`is_default: true`) swaps the key with the current default for the same `rail_scope`, if there is one, which becomes an ordinary untagged key. Only untagged keys can be promoted. **Demoting** (`is_default: false`) needs no replacement — the payment type is left without a default. **Replacing the key** (`api_key`) keeps the label, tag and payment types. The previous key is revoked once the new one is stored. operationId: update_payment_connection parameters: - in: path name: id required: true schema: type: string format: uuid description: The key's `id`, as returned when it was added or listed. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PaymentConnectionUpdateRequest' examples: rename: summary: Rename value: label: Nevada ACH (primary) promote: summary: Make this key the default for its rail_scope value: is_default: true replace_key: summary: Replace the key value: api_key: 0f1e2d3c4b5a69788796a5b4c3d29b1d responses: '200': description: The key as it is now. content: application/json: schema: $ref: '#/components/schemas/PaymentConnection' example: id: 5da36538-d683-40c6-8cbe-330b90b373b0 label: Debit card key merchant_ref: null rail_scope: card is_default: true key_last4: 9b1d last_poll_at: '2026-09-01T06:12:44Z' access_scope: lender_admins created_at: '2026-08-28T15:06:02Z' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' examples: merchant_ref_sent: summary: merchant_ref cannot be changed value: status: error status_code: 400 error: code: BAD_REQUEST message: >- Validation error: body.merchant_ref: Extra inputs are not permitted timestamp: '2026-08-28T15:06:02Z' suggestion: Check request parameters and body. tagged_key_promoted: summary: A tagged key cannot be the default value: status: error status_code: 400 error: code: BAD_REQUEST message: A tagged key cannot be made the default key timestamp: '2026-08-28T15:06:02Z' suggestion: >- Key 'acme-nv' is reached by naming its tag. Add or promote an untagged key to serve enrollments that name none. nothing_to_change: summary: Empty body value: status: error status_code: 400 error: code: BAD_REQUEST message: >- Validation error: body: Value error, Send at least one of label, rail_scope, is_default or api_key timestamp: '2026-08-28T15:06:02Z' suggestion: Check request parameters and body. '401': $ref: '#/components/responses/Unauthorized' '404': description: No key with this id for your account. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: status: error status_code: 404 error: code: NOT_FOUND message: No payment connection with that id for this requester timestamp: '2026-08-28T15:06:02Z' suggestion: '' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' examples: rail_has_default: summary: Moving a default key onto a rail_scope that already has one value: status: error status_code: 409 error: code: CONFLICT message: A default key for debit card already exists timestamp: '2026-08-28T15:06:02Z' suggestion: '' tag_has_rail: summary: Moving a tagged key onto a rail_scope its tag already covers value: status: error status_code: 409 error: code: CONFLICT message: Tag 'acme-nv' already has a debit card key timestamp: '2026-08-28T15:06:02Z' suggestion: '' '500': $ref: '#/components/responses/InternalServerError' components: schemas: PaymentConnectionUpdateRequest: type: object minProperties: 1 additionalProperties: false description: > Send only the fields to change. At least one is required. `merchant_ref` is not accepted — a tag is fixed when the key is added. properties: label: type: string minLength: 1 maxLength: 80 description: A new name for the key. rail_scope: type: string enum: - ach - card - both description: > The payment types this key can take. A default key cannot move onto a `rail_scope` that already has a default, and a tagged key cannot move onto one its tag already has a key for. is_default: type: boolean description: > `true` promotes an untagged key to default for its `rail_scope`, swapping with the current default for that scope if there is one. `false` demotes it and leaves the scope without a default. api_key: type: string minLength: 1 description: > A replacement key from your processor. The previous key is revoked once this one is stored; if it cannot be stored, the previous key stays in place. PaymentConnection: type: object description: One registered key. Never includes the key itself. properties: id: type: string format: uuid description: Use this to update or delete the key. label: type: string description: The name you gave the key. merchant_ref: type: - string - 'null' description: | The tag enrollments name to settle to this key, or `null` for a default or unused key. rail_scope: type: string enum: - ach - card - both description: The payment types this key can take. is_default: type: boolean description: Whether this is the default key for its `rail_scope`. key_last4: type: - string - 'null' description: The last four characters of the stored key, to tell keys apart. last_poll_at: type: - string - 'null' format: date-time description: | When Rightfoot last read payment results through this key. `null` until the first read. access_scope: type: string description: >- Reserved for a future permissions setting. Always `lender_admins` today. created_at: type: string format: date-time description: When the key was added. ApiErrorResponse: type: object properties: status: type: string description: Status of the error, either "error" or "success" status_code: type: integer description: HTTP status code of the error error: type: object properties: code: type: string description: Error code (e.g., "RESOURCE_NOT_FOUND") message: type: string description: Detailed error message. details: type: string description: Additional details about the error timestamp: type: string format: date-time description: Time the error occurred suggestion: type: string description: Suggested action to resolve the error documentation_url: type: string format: uri description: URL to the documentation for the error responses: Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: status: error status_code: 401 error: code: UNAUTHORIZED message: Invalid API key provided. timestamp: '2024-09-16T12:01:00Z' suggestion: Please check your API key. documentation_url: https://api.rightfoot.com/docs InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' example: status: error status_code: 500 error: code: INTERNAL_SERVER_ERROR message: An unexpected error occurred while retrieving the balances. timestamp: '2024-09-16T12:11:00Z' suggestion: >- Please try again later. If the problem persists, contact our support team. documentation_url: https://api.rightfoot.com/docs securitySchemes: BearerAuth: type: http scheme: bearer description: > Authentication to the API is performed via Bearer Token Authentication. Provide your API key as the bearer token in the Authorization header. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. ````