Temporary credentials (STS)

Temporary credentials (STS) are an access key + secret key pair plus a session token, with an expiration time. OtterStorage issues them instantly from the bucket console, they grant access to that bucket only, and they stop working once they expire. They're ideal for CI/CD, scripts and third parties, because you never hand out permanent keys.

When to use temporary credentials

• CI/CD pipelines uploading artifacts or backups: use credentials that expire when the job ends.
• One-off scripts or scheduled tasks that shouldn't embed a permanent key.
• Third parties or collaborators who need scoped, time-limited access.
• Any case where you'd rather a leaked credential expire on its own in hours instead of staying valid indefinitely.

If you need permanent access for a stable integration, use per-bucket access keys. Temporary and permanent credentials coexist fine.

Generate them from the console

Temporary credentials are issued from the bucket console itself:

• Open the bucket in the OtterStorage console.
• Go to the Temporary credentials (STS) section.
• Pick the duration (e.g. 1, 4 or 12 hours) and click Generate temporary credentials.
• OtterStorage shows you once the access key, secret key, session token and expiry time.

The result looks like this:

Access key ID:     STSXMPL7TEMP9QZ2A0B
Secret access key: aB3xY9kLpQ7mN2vWcR5tZ8dF1gH4jK6sUe0oI2pL
Session token:     FQoGZXIvYXdzE...very-long...Q==
Bucket:            my-first-bucket
Endpoint:          https://es-mad-1.s3.otterstorage.io
Expires:           in 1 hour

Copy them right away: like access keys, the secret and token are not shown again. There's no need to revoke them: they expire on their own once the duration is up.

Use them with AWS CLI

Unlike a permanent key, temporary credentials also require the session token. With AWS CLI you pass it via environment variables:

export AWS_ACCESS_KEY_ID="STSXMPL7TEMP9QZ2A0B"
export AWS_SECRET_ACCESS_KEY="aB3xY9kLpQ7mN2vWcR5tZ8dF1gH4jK6sUe0oI2pL"
export AWS_SESSION_TOKEN="FQoGZXIvYXdzE...very-long...Q=="
export AWS_DEFAULT_REGION="eu-mad"
export AWS_ENDPOINT_URL="https://es-mad-1.s3.otterstorage.io"

# Only works on the bucket they were generated for
aws s3 ls s3://my-first-bucket

When the token expires, any request returns an expired-credentials error: generate new ones from the console.

Use them with an SDK (boto3)

From code, pass aws_session_token along with the keys when creating the client:

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://es-mad-1.s3.otterstorage.io",
    region_name="eu-mad",
    aws_access_key_id="STSXMPL7TEMP9QZ2A0B",
    aws_secret_access_key="aB3xY9kLpQ7mN2vWcR5tZ8dF1gH4jK6sUe0oI2pL",
    aws_session_token="FQoGZXIvYXdzE...very-long...Q==",
)

resp = s3.list_objects_v2(Bucket="my-first-bucket")
for obj in resp.get("Contents", []):
    print(obj["Key"], obj["Size"])

Long jobs: programmatic access with auto-refresh

Temporary credentials do not auto-renew and last at most 12 hours. For long or unattended processes (CI/CD, backups) you don't want to regenerate them by hand. The answer is a service credential: a long-lived key with no S3 permissions whose only power is to request temporary credentials for your bucket (AssumeRole). Your SDK uses it to refresh the tokens on its own when they expire.

• Create it in the bucket's Programmatic access (auto-refreshing) section. Its access key + secret key and a ready-to-copy snippet are shown once.
• It's revocable instantly from the console; on its own it cannot touch S3, only obtain tokens scoped to that bucket.

boto3 example that auto-refreshes credentials (RefreshableCredentials):

import boto3
from botocore.credentials import RefreshableCredentials
from botocore.session import get_session

ENDPOINT   = "https://es-mad-1.s3.otterstorage.io"
REGION     = "eu-mad"
ROLE_ARN   = "arn:aws:iam::RGW...:role/bkr-123"
SVC_KEY    = "SVCXMPL..."
SVC_SECRET = "..."   # keep it in your secrets manager

def _refresh():
    sts = boto3.client("sts", endpoint_url=ENDPOINT, region_name=REGION,
                       aws_access_key_id=SVC_KEY, aws_secret_access_key=SVC_SECRET)
    c = sts.assume_role(RoleArn=ROLE_ARN, RoleSessionName="job", DurationSeconds=3600)["Credentials"]
    return {"access_key": c["AccessKeyId"], "secret_key": c["SecretAccessKey"],
            "token": c["SessionToken"], "expiry_time": c["Expiration"].isoformat()}

sess = get_session()
sess._credentials = RefreshableCredentials.create_from_metadata(_refresh(), _refresh, "sts-assume-role")
s3 = boto3.Session(botocore_session=sess).client("s3", endpoint_url=ENDPOINT, region_name=REGION)
# s3 auto-refreshes the temporary credentials on expiry; the job is not interrupted.

You can also use the aws-assume-role-lib library, which handles the automatic refresh for you.

Scope and limits

• Single-bucket access. The credentials can only operate on the bucket they were generated for; any other returns AccessDenied.
• They expire on their own. Once the duration is up they stop working; they are not renewed automatically.
• Not stored. OtterStorage doesn't keep the secret or token: if you lose them, generate new ones.
• No manual revocation needed. Because of their short life, the natural way to "cut" access is to let them expire.

Best practices

• Pick the shortest duration that covers your task: smaller exposure window.
• Generate a set per task/job instead of reusing the same everywhere.
• Pass them via environment variables or your secrets manager, never in code or the repo.
• For permanent use of a stable integration, use per-bucket access keys.

Summary

• Temporary credentials (STS) are access key + secret key + session token with an expiry, scoped to one bucket.
• Generate them in the bucket's Temporary credentials (STS) section by choosing a duration; they're shown once.
• To use them you must add the session token (AWS_SESSION_TOKEN env var or aws_session_token in the SDK).
• They expire on their own, only access their bucket and are not stored. For permanent access, use per-bucket access keys.

What's next? Review per-bucket access keys, connect with AWS CLI, or protect critical objects with Object Lock.