Skip to content
Console
On this page

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

FieldTypeWhat it is
namestringThe name of the bucket. Required.
credential_ttldurationHow 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

FieldTypeWhat it is
s3S3ConnectionHow to reach the same bucket over S3, with keys minted by this call. Unset while the bucket is not served over S3.
endpointstringThe URL clients send object requests to through the Data API; the same as status.endpoint. Output only.

S3Connection

FieldTypeWhat it is
endpointstringThe S3 endpoint URL, for example https://s3.sylphx.net. One endpoint serves every bucket.
regionstringThe SigV4 region name to sign with.
path_styleboolTrue: 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.
bucketstringThe S3 bucket name to put in the path and in signed requests.
access_key_idstringThe access key id.
secret_access_keystringThe secret access key. Never returned again.
session_tokenstringThe session token to send as X-Amz-Security-Token; empty when the keys are not temporary credentials of a session. Never returned again.
expire_timetimestampWhen the keys stop working; always set. A presigned URL made with them stops working then too, whatever its own expiry says.
presignS3PresignRulesWhat presigned URLs and multipart uploads may do on this endpoint.

S3PresignRules

FieldTypeWhat it is
max_expiresdurationThe 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.
methodsstring[]Methods a presigned URL may sign on an object: GET and HEAD to read, PUT to write in one request.
max_single_put_bytesint64A single PUT carries at most this many bytes (5 GiB); larger bodies use multipart.
min_part_bytesint64A 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_bytesint64A part is at most this many bytes (5 GiB).
max_partsint32An upload has at most this many parts (10000, numbered from 1).

Errors

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