Connect a bucket
Returns where to reach the bucket: the Data API address, and, once the bucket is served over S3, an S3 endpoint with keys scoped to this one…
Returns where to reach the bucket: the Data API address, and, once the bucket is served over S3, an S3 endpoint with keys scoped to this one bucket (s3). It carries no username or password; each call mints new S3 keys, and a client signs with those.
- Path
POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/buckets/bucket:connect - Scope
data:write - Effect
read— nothing is written. - Collection buckets
Request
| Field | Type | What it is |
|---|---|---|
name | string | The name of the bucket. Required. |
credential_ttl | duration | How long the S3 keys last: 900s to 604800s (7 days), default 3600s. Ask for what the work needs (a server that signs 7-day URLs asks for 604800s); connect again for fresh keys, they are cheap. |
Response
| Field | Type | What it is |
|---|---|---|
s3 | S3Connection | How to reach the same bucket over S3, with keys minted by this call. Unset while the bucket is not served over S3. |
endpoint | string | The URL clients send object requests to through the Data API; the same as status.endpoint. Output only. |
S3Connection
| Field | Type | What it is |
|---|---|---|
endpoint | string | The S3 endpoint URL, for example https://s3.sylphx.net. One endpoint serves every bucket. |
region | string | The SigV4 region name to sign with. |
path_style | bool | True: address the bucket in the path ({endpoint}/{bucket}/{key}); the endpoint has no per-bucket DNS name, so a client that defaults to virtual-hosted style must be told to use path style. |
bucket | string | The S3 bucket name to put in the path and in signed requests. |
access_key_id | string | The access key id. |
secret_access_key | string | The secret access key. Never returned again. |
session_token | string | The session token to send as X-Amz-Security-Token; empty when the keys are not temporary credentials of a session. Never returned again. |
expire_time | timestamp | When the keys stop working; always set. A presigned URL made with them stops working then too, whatever its own expiry says. |
presign | S3PresignRules | What presigned URLs and multipart uploads may do on this endpoint. |
S3PresignRules
| Field | Type | What it is |
|---|---|---|
max_expires | duration | The longest X-Amz-Expires accepted: 604800s (7 days). Keys that live shorter cut a URL's life short; ask credential_ttl for a longer lifetime when a URL must outlive the default keys. |
methods | string[] | Methods a presigned URL may sign on an object: GET and HEAD to read, PUT to write in one request. |
max_single_put_bytes | int64 | A single PUT carries at most this many bytes (5 GiB); larger bodies use multipart. |
min_part_bytes | int64 | A multipart upload presigns each of CreateMultipartUpload (POST?uploads), UploadPart (PUT?partNumber&uploadId), ListParts (GET?uploadId, to resume after a dropped part), CompleteMultipartUpload (POST?uploadId) and AbortMultipartUpload (DELETE?uploadId). Every part but the last is at least this many bytes (5 MiB). |
max_part_bytes | int64 | A part is at most this many bytes (5 GiB). |
max_parts | int32 | An upload has at most this many parts (10000, numbered from 1). |
Errors
UNAUTHENTICATED— No valid key or token was presented.PERMISSION_DENIED— The key lacks the method's permission.RESOURCE_NOT_FOUND— The named Resource does not exist or is not visible.INVALID_FIELD— A field failed validation.INVALID_STATE— The Resource is in a state that forbids the call.
Every error arrives in the body Errors describes.
Examples
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/buckets/bucket:connect" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'