Custom S3 Write Destination

By default, AudioShake serves task outputs from AudioShake-hosted storage with short-lived download links. With a storage integration, you can read inputs from and write outputs to a prefix in your own S3 bucket. This is useful for keeping audio in your own storage, meeting data-residency requirements, or wiring outputs straight into an existing pipeline.

S3 is supported today for both reading inputs and writing outputs. When using a storage integration, pass storageIntegrationId and provide a url with an s3:// scheme. assetId and HTTP urls are not supported with a storage integration.

How it works

You create an IAM role in your AWS account that AudioShake can assume.
You register the integration in AudioShake — this returns an External ID unique to your integration.
You add the External ID to your role’s trust policy.
You include storageIntegrationId and both a url and a writeDestination with an s3:// scheme in your /tasks requests.

At runtime, AudioShake assumes your role via STS and uses those short-lived credentials to read your inputs and write your outputs. AudioShake never stores long-lived AWS keys for your account.

Setup

1. Create an S3 bucket

In the AWS console, create the bucket AudioShake should read from and write to (or use an existing one). Bucket names are globally unique — pick something like acme-audioshake-outputs.

2. Create an IAM role in your AWS account

In the AWS IAM console, create a new role — for example, AudioshakeS3AccessRole. The role needs two policies: a trust policy that lets AudioShake assume the role, and a permissions policy that grants read and write access to your bucket prefix. Trust policy. On the first step of the role wizard (“Select trusted entity”), choose Custom trust policy — not “AWS account” — so you can trust AudioShake’s specific role rather than its entire account. Paste the JSON below into the editor. The Principal is AudioShake’s published service ARN — copy it verbatim. The External ID is a placeholder for now; you’ll fill it in after registering the integration in step 4.

Trust policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AudioshakeServicesS3Access",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::874456856160:role/AudioshakeServicesS3AccessRole"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "<EXTERNAL_ID_PLACEHOLDER>"
        }
      }
    }
  ]
}

Permissions policy. Continue through the wizard. On the “Add permissions” step you can either skip it and add an inline policy after the role is created, or attach the policy now by clicking Create policy, switching to the JSON editor, and pasting the block below. Replace <BUCKET_NAME> and <PREFIX> with your bucket and the prefix AudioShake should read from and write under (e.g. outputs). GetObject is required to read s3:// inputs. If your inputs and outputs live under different prefixes, include both in Resource.

Permissions policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadAndWriteObjectsInAssignedBucket",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:AbortMultipartUpload",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::<BUCKET_NAME>",
        "arn:aws:s3:::<BUCKET_NAME>/<PREFIX>/*"
      ]
    }
  ]
}

AbortMultipartUpload is needed for large files; ListBucket is needed for testing access.

3. (Optional) Restrict access via a bucket policy

For defense-in-depth, you can also add a bucket policy that allows only this role to read from and write to the prefix. In the bucket’s Permissions tab, set the bucket policy to:

Bucket policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowRoleReadAndWrite",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/AudioshakeS3AccessRole"
      },
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:AbortMultipartUpload",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::<BUCKET_NAME>",
        "arn:aws:s3:::<BUCKET_NAME>/<PREFIX>/*"
      ]
    }
  ]
}

4. Register the integration with AudioShake

You can register the integration through the Dashboard or via the API.

Dashboard
API

In the AudioShake Dashboard, go to Settings > Storage Integrations and click Add storage integration. Fill in:

Type — AWS S3
Bucket / Storage name — your bucket name (no s3:// prefix or path)
AWS region — e.g. us-east-1
Role ARN — the ARN of the role you created in step 2

After creating the integration, the Dashboard displays the integration ID and a generated External ID. Copy both — you’ll pass the ID as storageIntegrationId when creating tasks, and you’ll need the External ID in step 5.

Send a POST to /storage-integrations:

{
  "type": "aws",
  "storageName": "<BUCKET_NAME>",
  "authConfig": {
    "roleArn": "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/AudioshakeS3AccessRole",
    "region": "us-east-1"
  }
}

The response includes a generated externalId:

{
  "id": "<storage-integration-id>",
  "clientId": "<client-id>",
  "type": "aws",
  "storageName": "<BUCKET_NAME>",
  "authConfig": {
    "roleArn": "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/AudioshakeS3AccessRole",
    "region": "us-east-1",
    "externalId": "<audioshake-generated-id>"
  },
  "createdAt": "2026-04-21T23:44:21.346Z",
  "updatedAt": "2026-04-21T23:44:21.346Z"
}

Save the id — you’ll pass it as storageIntegrationId when creating tasks. Save the externalId — you’ll need it in step 5.

5. Add the External ID to your trust policy

Back in the AWS IAM console, open your role’s Trust relationships tab and replace <EXTERNAL_ID_PLACEHOLDER> with the External ID from step 4:

"Condition": {
  "StringEquals": {
    "sts:ExternalId": "<AUDIOSHAKE_GENERATED_EXTERNAL_ID>"
  }
}

Save the policy. The integration is now ready to use.

6. (Optional) Test the integration

Verify that AudioShake can write to your bucket by sending a POST to /storage-integrations/test:

{
  "writeDestination": "s3://<BUCKET_NAME>/<PREFIX>"
}

AudioShake looks up the matching integration, assumes your role, and writes a small test file at <writeDestination>/.verify/<timestamp>_<uuid>.json. A 200 response means the integration is working.

The writeDestination you test must start with the prefix you granted in your permissions policy. If your policy’s Resource is arn:aws:s3:::my-bucket/outputs/*, the verify object must land under outputs/ — test with "s3://my-bucket/outputs", not "s3://my-bucket".

Using a storage integration

Once the integration is active, include storageIntegrationId in your Create Task request. The input url must be an s3:// URI in the registered bucket, and writeDestination must also be an s3:// URI under that bucket:

{
  "url": "s3://acme-audioshake-outputs/inputs/song.wav",
  "storageIntegrationId": "<storage-integration-id>",
  "writeDestination": "s3://acme-audioshake-outputs/outputs",
  "targets": [
    { "model": "vocals", "formats": ["wav"] },
    { "model": "drums", "formats": ["mp3"] }
  ]
}

Use the id returned when you registered the integration (see step 4) as storageIntegrationId.

If you omit storageIntegrationId or writeDestination, outputs are written to AudioShake-hosted storage by default — your custom integration is not used. When using a storage integration, url must be an s3:// path; a public HTTPS URL is not sufficient.

Where outputs land

AudioShake writes outputs under your writeDestination by task:

s3://<bucket>/<prefix>/<taskId>/*

This keeps each task’s outputs isolated and avoids accidental overwrites between tasks. The full S3 keys are returned on the Task object alongside the standard output[].link download URLs.

Path rules

storageIntegrationId is required and must match a registered storage integration.
url must begin with s3:// followed by a bucket and object key in that integration’s bucket.
writeDestination must begin with s3:// followed by a bucket and a prefix.
The bucket in url and writeDestination must match the registered storage integration.

Security

AudioShake assumes your role only at task runtime, with a session named audioshake-task-<taskId> for auditability in CloudTrail.
Access is bounded by the permissions policy you attach to the role — AudioShake can only do what you grant.
The External ID condition prevents the confused-deputy problem — without it, another AudioShake customer could not be tricked into assuming your role.
You can revoke access immediately by removing the trust relationship, detaching the permissions policy, or deleting the role.

Troubleshooting

Symptom	Likely cause
Task is rejected on submit	Missing `storageIntegrationId`, `url` is not an `s3://` path, or the bucket doesn’t match the registered storage integration
Task fails with an `AssumeRole` error	Trust policy missing AudioShake’s principal, or the External ID doesn’t match
Task creates but reads or writes fail with access denied	Permissions policy doesn’t grant `s3:GetObject` on the input key or `s3:PutObject` on the `writeDestination` prefix, or the bucket policy restricts the role
Outputs land in AudioShake storage instead of your bucket	`storageIntegrationId` or `writeDestination` was omitted from the `/tasks` request

API Overview

Assets

Tasks

How it works

Setup

1. Create an S3 bucket

2. Create an IAM role in your AWS account

3. (Optional) Restrict access via a bucket policy

4. Register the integration with AudioShake

5. Add the External ID to your trust policy

6. (Optional) Test the integration

Using a storage integration

Where outputs land

Path rules

Security

Troubleshooting

​How it works

​Setup

​1. Create an S3 bucket

​2. Create an IAM role in your AWS account

​3. (Optional) Restrict access via a bucket policy

​4. Register the integration with AudioShake

​5. Add the External ID to your trust policy

​6. (Optional) Test the integration

​Using a storage integration

​Where outputs land

​Path rules

​Security

​Troubleshooting

How it works

Setup

1. Create an S3 bucket

2. Create an IAM role in your AWS account

3. (Optional) Restrict access via a bucket policy

4. Register the integration with AudioShake

5. Add the External ID to your trust policy

6. (Optional) Test the integration

Using a storage integration

Where outputs land

Path rules

Security

Troubleshooting