> ## 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.
# Create Location
> Store a new location (a credential) in your workspace.
A **location** is a stored credential — the `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`.
```bash cURL theme={null}
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" }
}'
```
```javascript JavaScript theme={null}
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();
```
```python Python theme={null}
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()
```
```json 201 Created theme={null}
{
"id": "3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83",
"provider": "s3",
"label": "prod-backups",
"metadata": { "region": "us-east-1" }
}
```
```json 422 Unprocessable Entity theme={null}
{
"error": 422,
"message": "invalid secret"
}
```
## OpenAPI
````yaml POST /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:
post:
summary: Create Location
description: >-
Store a new location (a credential) for the authenticated workspace.
Supply the `provider`, a human-readable `label`, and the provider-typed
`secret`; the secret is encrypted at rest and is never returned by any
endpoint. The response is the non-secret projection of the new location.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- provider
- label
- secret
properties:
provider:
type: string
description: >-
The storage backend to authenticate against. Immutable once
set.
enum:
- s3
- r2
- wasabi
- b2
- gcs
- azureblob
- dropbox
- drive
- onedrive
- box
example: s3
label:
type: string
description: >-
Human-readable name for the location. Required and
non-empty. Need not be unique.
example: prod-backups
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
responses:
'201':
description: Location created.
content:
application/json:
schema:
$ref: '#/components/schemas/Location'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'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
Error:
type: object
required:
- error
- message
properties:
error:
type: integer
message:
type: string
responses:
Error:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````