Replace Location Secret

PUT

locations

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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"
    }
  }'

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();

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()

{
  "id":       "3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83",
  "provider": "s3",
  "label":    "prod-backups",
  "metadata": { "region": "us-east-1" }
}

{
  "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"
    }
  ]
}

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.

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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"
    }
  }'

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();

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()

{
  "id":       "3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83",
  "provider": "s3",
  "label":    "prod-backups",
  "metadata": { "region": "us-east-1" }
}

{
  "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"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Address the location by name or id, plus the new secret.

secret

object

required

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"
}

name

string

The location name (its label). Resolved to a single location; if the name matches several, also send id to pick one.

Example:

"prod-backups"

string

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"

metadata

object

Optional non-secret configuration stored alongside the secret (e.g. region).

Example:

{ "region": "us-east-1" }

Response

Secret rotated.

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.

string

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

enum<string>

The storage backend this location authenticates against, set at creation and immutable thereafter.

Available options:

s3,

r2,

wasabi,

b2,

gcs,

azureblob,

dropbox,

drive,

onedrive,

box

Example:

"s3"

label

string

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

object

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" }

Get Location

Update Location Label

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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"
    }
  }'

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();

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()

{
  "id":       "3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83",
  "provider": "s3",
  "label":    "prod-backups",
  "metadata": { "region": "us-east-1" }
}

{
  "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"
    }
  ]
}