Quickstart Guide for Cloud Storage

In this guide, you will learn how to get started with the Telnyx Storage API in just a few easy steps!

1. Review the Terms and Conditions

Go to https://portal.telnyx.com/#/app/storage/buckets and click on the “Get Started” button. This will prompt a pop up window where you can review and acknowledge the Telnyx Storage Terms and Conditions.

Regardless of how you plan on interacting with the API (whether through the portal, via a direct API integration, or using a third party tool/client), Telnyx Storage will only work after the Terms and Conditions have been acknowledged and accepted.

2. Get your Telnyx bearer token

Go directly to https://portal.telnyx.com/#/app/api-keys to retrieve your account’s API key. An API key should have been auto generated when your account was created.

To maintain S3 compatibility, use the following header format in the API request, where {your_api_key_here} is replaced with your Telnyx API key.

--header 'Authorization: AWS4-HMAC-SHA256 Credential={your_telnyx_api_key_here}/us-east-1/execute-api/aws4_request

Note: After pasting the above content, Kindly check and remove any new line added

Note: the AWS region and Service Name listed in the auth header are ignored by our backend systems. We will just parse and validate the bearer token from the header when you make an API request.

3. Create a bucket

Lets go ahead and create your first bucket. You can perform the CreateBucket command shown below, where {bucket_name} is replaced with the name of your bucket, and {your_telnyx_api_key_here} is replaced with the API key you identified in Step 1.

curl --location --request PUT 'https://storage.telnyx.com/{bucket_name}' \
--header 'Accept: text/xml' \
--header 'Authorization: AWS4-HMAC-SHA256 Credential={your_telnyx_api_key_here}/us-east-1/execute-api/aws4_request, SignedHeaders=accept;host, Signature=e53ba8e0c1cdd4ff3e543b8dd71efac4ca76e01d2a6498646d485195e75aa0fb'
--header 'Content-Type: application/xml' \

Note: After pasting the above content, Kindly check and remove any new line added

You can optionally define a region to assign the bucket to upon creation. Currently, the regions are denver, dallas, atlanta, or phoenix. If you do not assign a region, it will default to dallas. To define a region, pass the following text in the body of the request, where {region} is replaced with the region you wish to store the data in.

--data-raw '<CreateBucketConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <LocationConstraint>{region}</LocationConstraint>
</CreateBucketConfiguration>'

Note: After pasting the above content, Kindly check and remove any new line added

Additionally, we follow the same bucket naming conventions as S3, outlined here.

4. Upload an object

Now that you have created a bucket, let's upload an object into the bucket. Perform the PutObject command shown below, where {bucket_name} is replaced with the name of your bucket, {object_name} is replaced with the name of your object, {your_telnyx_api_key_here} is replaced with the API key you identified in Step 1, and {file_directory_path} is replaced with the path to the object you intend to upload.

curl --location --request PUT 'https://storage.telnyx.com/{bucket_name}/{object_name}' \
--header 'Content-Type: application/octet-stream' \
--header 'Authorization: AWS4-HMAC-SHA256 Credential={your_telnyx_api_key_here}/20221006/us-east-1/execute-api/aws4_request, SignedHeaders=content-type;host, Signature=9d7d89295a706559c670a03959d2429b4026eb20eb38a378d9e1e112e068fc81' \
--data-binary '@/{file_directory_path}'

Note: After pasting the above content, Kindly check and remove any new line added

Additionally, if you pass the --header 'x-amz-server-side-encryption: 1' header, your object will be encrypted based on AES-256 standards.

Note: We currently only allow characters designated as “Safe Characters” in the S3 Object Key naming guidelines, outlined here.

5. Retrieve an object

Now that your object is uploaded, let's get it back! To retrieve your object, perform the GetObject command shown below, where {bucket_name} is replaced with the name of your bucket, {object_name} is replaced with the name of your object, and {your_telnyx_api_key_here} is replaced with the API key you identified in Step 1.

curl --location --request GET 'https://storage.telnyx.com/{bucket_name}/{object_name}' \
--header 'Accept: application/octet-stream' \
--header 'Authorization: AWS4-HMAC-SHA256 Credential={your_telnyx_api_key_here}/us-east-1/execute-api/aws4_request, SignedHeaders=accept;host, Signature=1e81d13d11066a4aa4a8b3278cfe41c235a9fd57706605cfcd022513d3dd312c'

Note: After pasting the above content, Kindly check and remove any new line added