Custom S3 Write Destination - AudioShake Developers

By default, AudioShake serves task outputs from AudioShake-hosted storage with short-lived download links. With a storage integration, you can instead write outputs directly 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 write destinations are supported today. Google Cloud Storage and Azure Blob Storage are planned. Reading inputs from s3:// URIs is not yet supported — continue providing inputs via assetId or a public HTTPS url.

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 writeDestination in your /tasks requests.

At runtime, AudioShake assumes your role via STS and uses those short-lived credentials to 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 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 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 you want AudioShake to write under (e.g. outputs):

Permissions policy

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

3. (Optional) Restrict writes via a bucket policy

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

Bucket policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowWriterRolePutObject",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<YOUR_ACCOUNT_ID>:role/AudioshakeS3AccessRole"
      },
      "Action": [
        "s3:PutObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "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 a generated External ID. Copy it — you’ll need it 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 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 custom write destination

Once the integration is active, include writeDestination in your Create Task request as an s3:// URI under your registered bucket:

{
  "url": "https://example.com/song.wav",
  "writeDestination": "s3://acme-audioshake-outputs/outputs",
  "targets": [
    { "model": "vocals", "formats": ["wav"] },
    { "model": "drums", "formats": ["mp3"] }
  ]
}

If you omit writeDestination, outputs are written to AudioShake-hosted storage by default — your custom integration is not used.

Where outputs land

AudioShake organizes outputs under your writeDestination by task and target:

s3://<bucket>/<prefix>/<taskId>/targets/<targetId>/output/<filename>

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

writeDestination must begin with s3:// followed by a bucket and a prefix.
The bucket in writeDestination must match a 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	The bucket in `writeDestination` doesn’t match a 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 writes fail with access denied	Permissions policy doesn’t grant `s3:PutObject` on the `writeDestination` prefix, or the bucket policy restricts the role
Outputs land in AudioShake storage instead of your bucket	`writeDestination` was omitted from the `/tasks` request

​How it works

​Setup

​1. Create an S3 bucket

​2. Create an IAM role in your AWS account

​3. (Optional) Restrict writes 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 custom write destination

​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 writes 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 custom write destination

Where outputs land

Path rules

Security

Troubleshooting