> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byteport.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Replace Location Secret
> Rotate a location's secret in place.
Rotate a location's secret in place. The `provider` and `label` stay the same —
only the `secret` (and optionally `metadata`) is replaced. Use this to roll a key
without disturbing anything that refers to the location by name or id. The new
secret is validated against the location's existing provider, so its shape must
match; a mismatch is rejected with `422`.
Address the location by **`name`** or **`id`** in the same body as the new
secret; at least one is required. A non-unique `name` returns `409` with the
candidates — resend with the `id` of the one you want.
```bash cURL theme={null}
curl -X PUT https://api.byteport.com/v1/locations \
-H "Authorization: Bearer $BYTEPORT_API_KEY" \
-H "User-Agent: my-app/1.0" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-backups",
"secret": {
"access_key_id": "AKIAIOSFODNN7ROTATED",
"secret_access_key": "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"
}
}'
```
```javascript JavaScript theme={null}
const res = await fetch("https://api.byteport.com/v1/locations", {
method: "PUT",
headers: {
Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
"User-Agent": "my-app/1.0",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "prod-backups", // or id: "..."
secret: {
access_key_id: "AKIAIOSFODNN7ROTATED",
secret_access_key: "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",
},
}),
});
const location = await res.json();
```
```python Python theme={null}
import os, requests
location = requests.put(
"https://api.byteport.com/v1/locations",
headers={
"Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
"User-Agent": "my-app/1.0",
},
json={
"name": "prod-backups", # or "id": "..."
"secret": {
"access_key_id": "AKIAIOSFODNN7ROTATED",
"secret_access_key": "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",
},
},
).json()
```
```json 200 OK theme={null}
{
"id": "3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83",
"provider": "s3",
"label": "prod-backups",
"metadata": { "region": "us-east-1" }
}
```
```json 409 Conflict theme={null}
{
"error": "name is not unique; re-issue with an \"id\" field for one of the candidates",
"name": "prod-backups",
"candidates": [
{
"id": "3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83",
"provider": "s3",
"created_at": "2026-05-14T17:02:11Z",
"updated_at": "2026-06-01T09:44:20Z"
},
{
"id": "8c2e1f4a-9b3d-4e6f-a1c7-2d5b0e9f7a34",
"provider": "gcs",
"created_at": "2026-05-20T11:07:33Z",
"updated_at": "2026-05-20T11:07:33Z"
}
]
}
```
## OpenAPI
````yaml PUT /v1/locations
openapi: 3.1.0
info:
title: Byteport API
description: >-
The Byteport API lets you move, share, and manage files across every storage
location connected to your workspace through a single HTTP interface.
version: 1.0.0
servers:
- url: https://api.byteport.com
security:
- bearerAuth: []
paths:
/v1/locations:
put:
summary: Replace Location Secret
description: >-
Rotate a location's secret in place. Address the location by `name` or
`id`; its `provider` and `label` are unchanged, only the `secret` (and
optionally `metadata`) is replaced. The new secret is validated against
the location's existing provider. A concurrent modification returns
`409`.
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Address the location by `name` or `id`, plus the new `secret`.
properties:
name:
type: string
description: >-
The location name (its `label`). Resolved to a single
location; if the name matches several, also send `id` to
pick one.
example: prod-backups
id:
type: string
description: >-
The location's UUID. Addresses one location directly, or —
alongside `name` — selects which match of a non-unique name
to act on.
example: 3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83
secret:
type: object
additionalProperties: true
description: >-
The provider-typed secret object (shape depends on the
location's `provider`). For S3-family providers:
`access_key_id` and `secret_access_key`. For OAuth providers
(Dropbox, Google Drive, OneDrive, Box): `access_token`,
`refresh_token`, and `expiry`. For GCS:
`service_account_json`. A shape that doesn't match the
provider is rejected with `422`.
example:
access_key_id: AKIAIOSFODNN7EXAMPLE
secret_access_key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
metadata:
type: object
additionalProperties: true
description: >-
Optional non-secret configuration stored alongside the
secret (e.g. `region`).
example:
region: us-east-1
required:
- secret
responses:
'200':
description: Secret rotated.
content:
application/json:
schema:
$ref: '#/components/schemas/Location'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'404':
$ref: '#/components/responses/Error'
'409':
description: The `name` matches more than one location; resend with an `id`.
content:
application/json:
schema:
$ref: '#/components/schemas/LocationConflict'
'422':
$ref: '#/components/responses/Error'
components:
schemas:
Location:
type: object
description: >-
The non-secret projection of a location (a stored credential). Returned
by Create, Get, Replace, and Update Label. Never includes the secret
material — only the fields safe to display.
properties:
id:
type: string
description: >-
Unique identifier for the location (a UUID). Address a location by
this `id`, or by its `name` (label).
example: 3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83
provider:
type: string
description: >-
The storage backend this location authenticates against, set at
creation and immutable thereafter.
enum:
- s3
- r2
- wasabi
- b2
- gcs
- azureblob
- dropbox
- drive
- onedrive
- box
example: s3
label:
type: string
description: >-
The human-readable name for the location. Labels are **not unique**:
an account may reuse one across providers, and the same name can
match several locations — pass an `id` to disambiguate. Set at
creation and changed via Update Label.
example: prod-backups
metadata:
type: object
additionalProperties: true
description: >-
Non-secret, provider-specific configuration stored alongside the
secret (e.g. `region`, `scopes`, `account_email`). Byteport may
stamp additional display hints here. Omitted entirely when empty.
example:
region: us-east-1
LocationConflict:
type: object
description: >-
Returned with `409` by a single-location endpoint when the `name` in the
body matches more than one location. Re-issue the request with an `id`
field set to one of the candidates.
properties:
error:
type: string
description: Human-readable explanation of the ambiguity.
example: >-
name is not unique; re-issue with an "id" field for one of the
candidates
name:
type: string
description: The ambiguous location name from the request body.
example: prod-backups
candidates:
type: array
description: >-
Every location that carries this name. Choose one and resend with
its `id`.
items:
$ref: '#/components/schemas/LocationRef'
Error:
type: object
required:
- error
- message
properties:
error:
type: integer
message:
type: string
LocationRef:
type: object
description: >-
A credential addressed by its label ("location name"). Because labels
are not unique, a single name can resolve to several of these.
`provider` and the timestamps let you tell same-named credentials apart
and pick the `id` to act on.
properties:
id:
type: string
description: >-
The credential's UUID. Pass it back as the `?id=` query parameter to
disambiguate a non-unique name on the mutating Locations endpoints.
example: 3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83
provider:
type: string
description: The storage backend this credential authenticates against.
example: s3
created_at:
type: string
format: date-time
description: When the credential was created (RFC 3339, UTC).
example: '2026-05-14T17:02:11Z'
updated_at:
type: string
format: date-time
description: When the credential was last modified (RFC 3339, UTC).
example: '2026-06-01T09:44:20Z'
responses:
Error:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````