Skip to navigation

AWS S3 Storage

This page describes how to connect an AWS S3 bucket to Solvimon for data exports. Solvimon can write to your bucket in two ways: by assuming an IAM role in your AWS account, or with the access key and secret of an IAM user.


Choose an authentication method

IAM role (recommended)Access key and secret
Credentials you store or shareNone. Solvimon assumes your role with an external ID and gets temporary credentials that last one hour.A long-lived access key and secret for an IAM user.
Permissions neededs3:ListBucket and s3:PutObjectRead, write, delete and multipart upload permissions
File format in the bucketThe report file as Solvimon generated it: gzipped CSVCSV or Parquet
How to set it upSolvimon support, or the APIDesk or Solvimon support

Use the IAM role unless you need Parquet files in the bucket.


With this method, you create an IAM role in your AWS account and allow Solvimon to assume it. For each export, Solvimon calls sts:AssumeRole with an external ID that only your platform uses. It then uploads the report file to your bucket with the temporary credentials it gets back. No access key is stored on either side.

AssumeRole(role ARN, external ID) Temporary credentials (1 hour) PutObject(report file) Solvimon AWS STS (your account) S3 bucket (your account)

Requirements

  • An AWS account where you can create IAM roles and policies.
  • An S3 bucket for the exports. To create one, follow the AWS documentation.
  • To create the integration yourself instead of through Solvimon support: a Solvimon API key with permission to manage integrations and report subscriptions.

Setup

1

Get your external ID and the Solvimon principal from Solvimon

Contact Solvimon support to request an IAM role setup for S3 exports. Solvimon sends you two values:

ValueExampleUsed in
Solvimon principal ARN{SOLVIMON_PRINCIPAL_ARN}The trust policy of your role
External ID{EXTERNAL_ID}The trust policy of your role and the integration

Solvimon issues the external ID, and it’s unique to your platform. Don’t choose your own. A unique ID per customer is what stops another Solvimon customer from pointing an export at your role.

2

Create the permissions policy

In the IAM console, go to Policies → Create policy, open the JSON tab and paste the policy below. Replace {YOUR_BUCKET_NAME} with your bucket name and {YOUR_BUCKET_PATH} with the folder Solvimon writes to, for example solvimon.

Permissions policy
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "CheckBucketAccess",
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::{YOUR_BUCKET_NAME}"
},
{
"Sid": "WriteReports",
"Effect": "Allow",
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::{YOUR_BUCKET_NAME}/{YOUR_BUCKET_PATH}/*"
}
]
}

Solvimon needs s3:ListBucket to check that it can reach the bucket (an S3 HeadBucket call) and s3:PutObject to upload each report. It doesn’t read, list or delete objects.

If the bucket uses SSE-KMS encryption with a customer managed key, add a statement that allows kms:GenerateDataKey on that key:

KMS statement (SSE-KMS buckets only)
{
"Sid": "EncryptReports",
"Effect": "Allow",
"Action": "kms:GenerateDataKey",
"Resource": "arn:aws:kms:{REGION}:{ACCOUNT_ID}:key/{KEY_ID}"
}
3

Create the role

In the IAM console, go to Roles → Create role and choose Custom trust policy. Paste the trust policy below, using the two values from Solvimon:

Trust policy
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "{SOLVIMON_PRINCIPAL_ARN}"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "{EXTERNAL_ID}"
}
}
}
]
}

Attach the permissions policy from the previous step, name the role (for example solvimon-export) and create it. Copy the role ARN from the role’s summary page, for example arn:aws:iam::123456789012:role/solvimon-export.

Solvimon requests one-hour sessions, so keep the role’s maximum session duration at one hour or more. One hour is the AWS default.

4

Send the role details to Solvimon

Send these values to Solvimon support:

ValueExample
Role ARNarn:aws:iam::123456789012:role/solvimon-export
Bucket nameacme-billing-exports
Bucket pathsolvimon. Must match {YOUR_BUCKET_PATH} in the permissions policy.
Bucket regioneu-west-1

Solvimon creates the integration, checks that it can assume the role and reach the bucket, and points your report exports at it. To create the integration yourself, see Create the integration with the API.

Desk can only create S3 integrations that use an access key.

Create the integration with the API

Instead of sending the role details to Solvimon support, you can create the integration and the report exports yourself.

1

Create the integration

Create a DATA_EXPORT integration with POST /v1/integrations. Set authentication_type to IAM_ROLE and leave out the authentication block:

Create an S3 integration that uses an IAM role
curl -X POST https://test.api.solvimon.com/v1/integrations \
-H "X-API-KEY: <apiKey>" \
-H "Content-Type: application/json" \
-d '{
"reference": "s3-export",
"name": "S3 export",
"type": "DATA_EXPORT",
"data_export": {
"variant": "S3",
"s3": {
"bucket_name": "acme-billing-exports",
"bucket_path": "solvimon",
"bucket_region": "eu-west-1",
"authentication_type": "IAM_ROLE",
"role_arn": "arn:aws:iam::123456789012:role/solvimon-export",
"external_id": "<externalId>"
}
}
}'
FieldRequiredDescription
bucket_nameYesName of the S3 bucket.
bucket_pathYesFolder in the bucket that Solvimon writes to. Must match {YOUR_BUCKET_PATH} in the permissions policy.
bucket_regionYesAWS region of the bucket, for example eu-west-1.
authentication_typeYesIAM_ROLE.
role_arnYesARN of the role you created.
external_idYesThe external ID Solvimon gave you.

The response contains the integration’s id, which you need in the next steps.

Don’t send data_export.transport_type. Solvimon sets it from the authentication type and overwrites any value in the request.

2

Check the connection

After you create the integration, Solvimon assumes the role and checks that it can reach the bucket. Fetch the integration with GET /v1/integrations/{id} to see the result:

Get the integration
curl https://test.api.solvimon.com/v1/integrations/<integrationId> \
-H "X-API-KEY: <apiKey>"
Response (trimmed)
{
"object_type": "INTEGRATION",
"id": "<integrationId>",
"reference": "s3-export",
"status": "ACTIVE",
"type": "DATA_EXPORT"
}

ACTIVE means the check passed. ERROR means it failed, and message contains the reason. The usual causes are a mismatch between the external ID in the trust policy and the integration, a wrong principal ARN in the trust policy, or a missing s3:ListBucket permission. Exports to an integration that is still PENDING or TESTING wait until the check finishes.

3

Send reports to the bucket

Point a report subscription at the integration with POST /v1/report-subscriptions. Set export_location.integration_id to the integration’s id:

Export a report to S3 on the 1st of every month
curl -X POST https://test.api.solvimon.com/v1/report-subscriptions \
-H "X-API-KEY: <apiKey>" \
-H "Content-Type: application/json" \
-d '{
"report_configuration_id": "<reportConfigurationId>",
"format": "CSV",
"schedule": { "time_of_day": 6, "day_of_month": 1 },
"active": true,
"export_location": {
"integration_id": "<integrationId>",
"variant": "S3",
"s3": {
"path_format": "${YEAR}/${MONTH}/${DAY}"
}
}
}'

See Reports for report configurations, schedules and parameters. To move an existing subscription to the new integration, update its export_location with PATCH /v1/report-subscriptions/{id}.

Where files are written

Solvimon builds each object key from three parts: the bucket path, the expanded path format, and the report’s file name.

  • Bucket path: export_location.s3.bucket_path on the report subscription if set, otherwise bucket_path on the integration. If you override it on the subscription, make sure the permissions policy covers that folder too.
  • Path format: export_location.s3.path_format is optional. It’s expanded in UTC at upload time and supports these placeholders: ${YEAR}, ${MONTH}, ${DAY}, ${HOUR}, ${MINUTE}, ${SECOND}, ${MILLISECOND}, ${EPOCH} (milliseconds) and ${UUID}.
  • Prefix or folder: if the last segment of the path format ends in _ or -, Solvimon uses it as a prefix on the file name. Otherwise the whole path format is a folder.
bucket_pathpath_formatObject key
solvimonnot setsolvimon/<file name>
solvimon${YEAR}/${MONTH}/${DAY}solvimon/2026/11/16/<file name>
solvimon${YEAR}/${MONTH}/${EPOCH}_solvimon/2026/11/1794787200000_<file name>

What you see in AWS

  • File contents: Solvimon uploads the report file as it generated it, in one PutObject call: a gzipped CSV file (.csv.gz). export_location.s3.format_type has no effect with an IAM role, so files aren’t converted to Parquet. For Parquet files in your bucket, use the access key method.
  • Object metadata: each object has the user metadata report-created-at, report-exported-at, source-last-modified and report-resource-id (shown in S3 with the x-amz-meta- prefix). Use report-resource-id to match a file to the report in Solvimon.
  • CloudTrail: each export appears as an AssumeRole event for your role with the session name solvimon-export-<platform ID>, followed by a PutObject from that session.

Switch from an access key to an IAM role

You can’t change the authentication method of an existing S3 integration. To switch:

  1. Set up the role following the steps above and send the role details to Solvimon support.
  2. Solvimon creates a new integration and moves your report exports to it once it’s ACTIVE. If you manage the exports through the API, update each report subscription so export_location.integration_id points to the new integration.
  3. When the first export arrives through the role, delete the old IAM user’s access key in AWS, then the user.

Access key and secret

Requirements

The following access is required for us to set-up a connection from Solvimon to your AWS S3 bucket.

  • An AWS Account with IAM privileges to grant read and list permissions for S3 buckets, or alternatively an existing S3 bucket with Access Key and Secret.
  • A project in AWS portal.

Setup

1

Create an AWS Access Key, Secret and a user policy

First of all, sign in to your AWS account. Follow the instructions to create an Access Key ID and Secret Access Key, which will be required to establish the connection to upload the Solvimon data to your S3 bucket. The IAM user associated with the credentials must be granted read and list permissions for the bucket and its objects. If you already have an existing Access Key and Secret, there is no need to create a new one.

This is a step to help you obtain the required permissions and credentials, and therefore the Access Key and Secret.

  1. Log in to Amazon AWS and open the IAM console.

  2. Go to Policies and then click Create Policies.

  3. Select JSON tab, and paste the following JSON in the policy editor, by substituting the variables with your bucket name (replace {YOUR_BUCKET_NAME}). It is relevant to know that in this JSON there are not only the policies for the user, but also to be able to manage the S3 bucket properly.

    IAM policy
    {
    "Version": "2012-10-17",
    "Statement": [
    {
    "Effect": "Allow",
    "Action": [
    "s3:PutObject",
    "s3:GetObject",
    "s3:DeleteObject",
    "s3:PutObjectAcl",
    "s3:ListBucket",
    "s3:ListBucketMultipartUploads",
    "s3:AbortMultipartUpload",
    "s3:GetBucketLocation"
    ],
    "Resource": ["arn:aws:s3:::{YOUR_BUCKET_NAME}/*", "arn:aws:s3:::{YOUR_BUCKET_NAME}"]
    }
    ]
    }
  4. Click now Create policy.

  5. In the IAM dashboard, go to Users and either create a new one or use an existing one.

  6. Go to Add Permissions and select Attach policies directly, where you have to find the policy that has just been created.

  7. Once the user with its permissions is created, select the Security credentials tab and click Create access key. Click Create access key to generate the keys.

2

Create an S3 Bucket

The S3 Bucket will be the destination where the data coming from Solvimon will be exported. To create a bucket, in case you don’t have one already for this purpose, you can follow this documentation.

3

Share the relevant information with Solvimon

FieldDescription
Key IDThe Access Key ID that was created in Step 1.
Access KeyThe Access Key Secret also created in Step 1.
Bucket NameThe name of the S3 Bucket destination for the data.
Bucket PathSubdirectory under the S3 bucket to sync the data into.
Bucket RegionRegion of the S3 bucket.

As soon as we receive this information we will reach out and work with you directly to set-up the relevant data exports.