Create Location
Store a new location (a credential) in your workspace.
curl -X POST 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 '{
"provider": "s3",
"label": "prod-backups",
"secret": {
"access_key_id": "AKIAIOSFODNN7EXAMPLE",
"secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
},
"metadata": { "region": "us-east-1" }
}'
const res = await fetch("https://api.byteport.com/v1/locations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
"User-Agent": "my-app/1.0",
"Content-Type": "application/json",
},
body: JSON.stringify({
provider: "s3",
label: "prod-backups",
secret: {
access_key_id: "AKIAIOSFODNN7EXAMPLE",
secret_access_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
},
metadata: { region: "us-east-1" }, // optional
}),
});
const location = await res.json();
import os, requests
res = requests.post(
"https://api.byteport.com/v1/locations",
headers={
"Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
"User-Agent": "my-app/1.0",
},
json={
"provider": "s3",
"label": "prod-backups",
"secret": {
"access_key_id": "AKIAIOSFODNN7EXAMPLE",
"secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
},
"metadata": {"region": "us-east-1"}, # optional
},
)
location = res.json()
{
"id": "3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83",
"provider": "s3",
"label": "prod-backups",
"metadata": { "region": "us-east-1" }
}
{
"error": 422,
"message": "invalid secret"
}
provider names the storage backend,
the label is the human-readable name you refer to it by, and the secret is
the provider-typed authentication material. The secret is encrypted at rest and
is never returned by any endpoint; the response is the non-secret projection
of the new location.
The shape of secret depends on provider. S3-family providers (s3, r2,
wasabi, b2, azureblob) take access_key_id and secret_access_key; OAuth
providers (dropbox, drive, onedrive, box) take access_token,
refresh_token, and expiry; gcs takes service_account_json. A secret whose
shape doesn’t match the provider is rejected with 422.
curl -X POST 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 '{
"provider": "s3",
"label": "prod-backups",
"secret": {
"access_key_id": "AKIAIOSFODNN7EXAMPLE",
"secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
},
"metadata": { "region": "us-east-1" }
}'
const res = await fetch("https://api.byteport.com/v1/locations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
"User-Agent": "my-app/1.0",
"Content-Type": "application/json",
},
body: JSON.stringify({
provider: "s3",
label: "prod-backups",
secret: {
access_key_id: "AKIAIOSFODNN7EXAMPLE",
secret_access_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
},
metadata: { region: "us-east-1" }, // optional
}),
});
const location = await res.json();
import os, requests
res = requests.post(
"https://api.byteport.com/v1/locations",
headers={
"Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
"User-Agent": "my-app/1.0",
},
json={
"provider": "s3",
"label": "prod-backups",
"secret": {
"access_key_id": "AKIAIOSFODNN7EXAMPLE",
"secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
},
"metadata": {"region": "us-east-1"}, # optional
},
)
location = res.json()
{
"id": "3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83",
"provider": "s3",
"label": "prod-backups",
"metadata": { "region": "us-east-1" }
}
{
"error": 422,
"message": "invalid secret"
}
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
The storage backend to authenticate against. Immutable once set.
s3, r2, wasabi, b2, gcs, azureblob, dropbox, drive, onedrive, box "s3"
Human-readable name for the location. Required and non-empty. Need not be unique.
"prod-backups"
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.
{
"access_key_id": "AKIAIOSFODNN7EXAMPLE",
"secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
Optional non-secret configuration stored alongside the secret (e.g. region).
{ "region": "us-east-1" }
Response
Location created.
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.
Unique identifier for the location (a UUID). Address a location by this id, or by its name (label).
"3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83"
The storage backend this location authenticates against, set at creation and immutable thereafter.
s3, r2, wasabi, b2, gcs, azureblob, dropbox, drive, onedrive, box "s3"
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.
"prod-backups"
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.
{ "region": "us-east-1" }
curl -X POST 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 '{
"provider": "s3",
"label": "prod-backups",
"secret": {
"access_key_id": "AKIAIOSFODNN7EXAMPLE",
"secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
},
"metadata": { "region": "us-east-1" }
}'
const res = await fetch("https://api.byteport.com/v1/locations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
"User-Agent": "my-app/1.0",
"Content-Type": "application/json",
},
body: JSON.stringify({
provider: "s3",
label: "prod-backups",
secret: {
access_key_id: "AKIAIOSFODNN7EXAMPLE",
secret_access_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
},
metadata: { region: "us-east-1" }, // optional
}),
});
const location = await res.json();
import os, requests
res = requests.post(
"https://api.byteport.com/v1/locations",
headers={
"Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
"User-Agent": "my-app/1.0",
},
json={
"provider": "s3",
"label": "prod-backups",
"secret": {
"access_key_id": "AKIAIOSFODNN7EXAMPLE",
"secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
},
"metadata": {"region": "us-east-1"}, # optional
},
)
location = res.json()
{
"id": "3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83",
"provider": "s3",
"label": "prod-backups",
"metadata": { "region": "us-east-1" }
}
{
"error": 422,
"message": "invalid secret"
}