AWS S3 Integration

Set up this integration to copy generated PDFs into an S3 bucket in your own AWS account.

This integration applies to all templates, submissions, and combined submissions in your account unless you specify API Token ID(s). When you specify API Token ID(s) then you can have multiple S3 buckets for different workflows or some workflows that don't upload to AWS at all.

You can configure what type of submissions will be uploaded to your S3 bucket:

  • Only Live (default)
  • Only Test
  • Both Live and Test

You can also configure different path templates for live and test submissions.

Authentication Methods

DocSpring supports two methods of authentication for AWS S3:

  1. Access Key Authentication
  2. Role-based Authentication

Access Key Authentication

This method uses AWS access keys directly. Here's how to set it up:

Create an S3 Bucket

  • Sign into your AWS account
  • Visit the S3 service
  • Click "Create bucket"
  • Choose a bucket name and select the correct AWS region
  • Click "Next", then configure your bucket options and permission
  • Click "Create bucket"

Create An IAM Policy With Limited Permissions

  • Visit the IAM service
  • Click "Policies"
  • Click "Create policy"
  • Under "Service", choose "S3"
  • Under "Actions", expand the "Write" section
    • Select the PutObject checkbox. (DocSpring does not need any other permissions)
  • Under "Resources", choose "Specific". Then click "Add ARN".
    • Paste your bucket name into "Bucket name"
    • Check the "Any" checkbox for "Object name"
    • Click "Add"
  • Click "Review policy"
  • Set a name for the new policy, e.g. "DocSpringS3Uploads"
  • Set a description, e.g. "Allows the DocSpring service to upload PDFs to our S3 bucket"
  • Click "Create policy"

Create An IAM User With Limited Permissions

  • Visit the IAM service
  • Click "Users"
  • Click "Add user"
  • Configure the username, e.g. "docspring-s3-uploads"
  • Under "Access type", select "Programmatic access"
  • Click "Next: Permissions"
  • Click the "Attach existing policies directly" option.
  • Find the policy you just created (use the Search box)
  • Select this policy by clicking the checkbox
  • Click "Next: Tags"
  • Skip the Tags section. Click "Next: Review"
  • Click "Create user"
  • Click "Show" under the "Secret access key".
  • Copy the Access key ID and Secret access key, and save these for later.

Role-based Authentication

This method uses AWS Security Token Service (STS) to assume an IAM role in your AWS account. This is the recommended approach as it's more secure than sharing access keys.

Create an IAM Role in Your AWS Account

  1. Create an IAM role with the following permissions:

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
      "Resource": ["arn:aws:s3:::YOUR_BUCKET_NAME/*"]
    }
  ]
}

  2. Add a trust relationship to allow DocSpring to assume this role:

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::691950705664:user/service/docspring-s3-cross-account"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

    Important: The role name must include docspring. This is a security measure that prevents you from accidentally allowing us to assume any other roles in your account.

  3. Configure the integration with:

    • Authentication Type: "Role-based Authentication"
    • Role ARN: The ARN of the role you created
    • Bucket Name
    • Region

Configuration

Required Fields

  • auth_type - The authentication method to use ("access_key" or "role")
  • bucket - The name of your S3 bucket
  • region - The AWS region where your bucket is located (e.g., "us-east-1")

For access key authentication:

  • access_key_id - Your AWS access key ID
  • secret_access_key - Your AWS secret access key

For role-based authentication:

  • role_arn - The ARN of the IAM role to assume

Path Templates

The path templates use the Liquid syntax. Available variables:

  • account_id (Your DocSpring Account ID) - Example: acc_X3gQR5GN6tS6tcYgJs
  • template_id - Example: tpl_eGc5CmFbPnCCmerqsx
  • template_name
    • All invalid characters are replaced with an underscore
  • submission_id - Example: sub_Gbxesk7Xf52Pq3KgT9
  • timestamp (Time when the submission was processed) - Example: 20180509094531
  • date - Example: 20180509
  • year - Example: 2018
  • month (Not zero-padded) - Example: 5
  • day (Not zero-padded) - Example: 9

For combined submissions:

  • combined_submission_id - Example: com_Zbetd3ayK4EK3J4Hf4

You can also use any values from the metadata object:

  • Access values with {{ metadata.<key> }}
  • All invalid characters are replaced with an underscore
  • Valid characters are: 0-9, a-z, A-Z, !-\_.\*'() (See the AWS docs)

Default templates:

submission_path_template: "submissions/{{ submission_id }}.pdf"
test_submission_path_template: "test_submissions/{{ submission_id }}.pdf"
combined_submission_path_template: "combined_submissions/{{ combined_submission_id }}.pdf"

FAQ

How can I configure the S3 integration to only upload certain PDFs?

You can use the "Submission Type" and "API Token IDs" fields to configure which PDFs will be uploaded to your S3 bucket.

For example, if you set "Submission Type" to live, then DocSpring will only upload live PDFs to S3 (without watermarks.) Test PDFs will be skipped. The other options are "test", and "all" (for both test and live PDFs.)

You can also provide a comma-separated list of API tokens in the "API Token IDs" field. If you provide one or more API token IDs, then DocSpring will only upload submissions (or combined submissions) that were created using this API token. You could use feature to set up S3 buckets for different environments (e.g. dev, staging, production, qa), and use separate API tokens for each environment. This would allow you to send your generated PDFs into the correct S3 bucket for each environment while sharing the same templates in a single DocSpring account.

Which authentication method should I use?

We recommend using role-based authentication as it's more secure than sharing access keys. With role-based authentication:

  • No long-term credentials are shared between DocSpring and your AWS account
  • You can easily revoke access by modifying the trust relationship
  • You have more granular control over permissions
  • You can use AWS CloudTrail to audit role assumption activities

Does DocSpring still keep a copy of the PDF?

Yes. This AWS S3 integration is just a one-way file upload, but DocSpring continues to store your template PDFs and generated PDFs. We serve our own copy of the generated PDF when you request a download URL. We will also use our own copy of the PDF when merging them into a "combined submission".

Does DocSpring delete the PDF from my S3 bucket when a submission expires?

No. DocSpring will only delete our own copy of the PDF when a submission expires. We will never delete a PDF in your custom S3 bucket.

How can I tell when the PDF has been uploaded to my custom S3 bucket?

One thing to be aware of is that the submission state will change to processed as soon as our copy of the PDF is ready, but it might take a few seconds before the PDF is uploaded into your custom S3 bucket. The AWS integration upload happens after the initial processing is completed.

If you need to know when the PDF is available in your own S3 bucket, you can check the actions array in the API response. This array will be empty before the submission is processed. As soon as the the submission is processed, it will contain an entry for the aws_s3_upload action. This action's state will be pending until the file has been uploaded into your S3 bucket, and then it will change to processed.

For example, here's how you could wait for the PDF to be uploaded to your own S3 bucket (in JavaScript):

const pdfHasBeenUploadedToS3Bucket = () => {
  if (submission['actions'].length === 0) return false
  const action = submission['actions'].find(
    (a) => a.action_type === 'aws_s3_upload'
  )
  return action && action.state === 'processed'
}

Another thing you could do is set up an AWS S3 event notification. You could send a webhook to your server as soon as the PDF has been uploaded to your S3 bucket. This means that you wouldn't need to do any polling.

What if my "path template" generates a duplicate key?

If a path template generates a duplicate key, any existing files will be overwritten with the new file. To protect against this case, you should enable "Versioning" for your S3 bucket. This means that you will always be able to restore an original file in case it is accidentally overwritten with a duplicate key. Your path template should also use at least one variable that is guaranteed to be unique, such as submission_id.

Note: Please don't rely on the timestamp variable to provide unique filenames, because multiple PDFs can be processed in the same second.

Troubleshooting

Common issues and solutions:

  1. Access Denied

    • For access keys: Verify the IAM user has correct permissions
    • For roles: Check the role's permissions and trust relationship
    • For roles: Ensure the role name includes docspring
    • For roles: Verify the trust relationship includes the DocSpring IAM user: arn:aws:iam::691950705664:user/service/docspring-s3-cross-account

  2. Invalid Credentials

    • For access keys: Ensure keys are correct and active
    • For roles: Verify the role ARN and trust relationship

  3. Path Template Errors

    • Check that all variables in your templates are valid
    • Ensure the template syntax is correct (use double curly braces)

  4. Region Mismatch

    • Confirm the region matches your S3 bucket's location

For additional help, contact DocSpring support.

results matching ""

    No results matching ""