What are valid S3 key names that can be accessed via the S3 rest API?

From the AWS docs, I understand that:

  • S3 key names can be any UNICODE name < 1024 chars
  • When using the GET OBJ, I need to URL encode the key name to access it.

However, these rules seem too permissive.

For instance, if I make a key called '../../d', a 400 ERROR occurs when I attempt to access it with the GET OBJECT API. Interestingly, I have no problem accessing '../d'.

Is there a document specifying what is and is not legal?


According to AWS S3 documentation:

Although you can use any UTF-8 characters in an object key name, the following key naming best practices help ensure maximum compatibility with other applications. Each application may parse special characters differently. The following guidelines help you maximize compliance with DNS, web safe characters, XML parsers, and other APIs.

Please find below the

Object Key Naming Guidelines from the AWS S3 official documentation


Safe characters

The following character sets are generally safe for use in key names:

  • Alphanumeric characters: 0-9 a-z A-Z
  • Special characters: ! - _ . * ' ( )

NOTE ABOUT THE DELIMITER ("/")

The following are examples of valid object key names:

  • 4my-organization

  • my.great_photos-2014/jan/myvacation.jpg

  • videos/2014/birthday/video1.wmv

Note that the Amazon S3 data model is a flat structure: you create a bucket, and the bucket stores objects. There is no hierarchy of subbuckets or subfolders; however, you can infer logical hierarchy using keyname prefixes and delimiters as the Amazon S3 console does.

e.g if you use Private/taxdocument.pdf as a key, it will create the Private folder, with taxdocument.pdf in it.

Amazon S3 supports buckets and objects, there is no hierarchy in Amazon S3. However, the prefixes and delimiters in an object key name, enables the Amazon S3 console and the AWS SDKs to infer hierarchy and introduce concept of folders.


Characters That Might Require Special Handling

The following characters in a key name may require additional code handling and will likely need to be URL encoded or referenced as HEX. Some of these are non-printable characters and your browser may not handle them, which will also require special handling:

  • Ampersand ("&")
  • 'At' symbol ("@")
  • Colon (":")
  • Comma (",")
  • Dollar ("$")
  • Equals ("=")
  • Plus ("+")
  • Question mark ("?")
  • ASCII character ranges 00–1F hex (0–31 decimal) and 7F (127 decimal.)
  • Semicolon (";")
  • Space – Significant sequences of spaces may be lost in some uses (especially multiple spaces)

Characters to Avoid

You should avoid the following characters in a key name because of significant special handling for consistency across all applications.

  • Backslash ("")
  • Caret ("^")
  • Grave accent / back tick ("`")
  • 'Greater Than' symbol (">")
  • 'Less Than' symbol ("<")
  • Left curly brace ("{")
  • Right curly brace ("}")
  • Right square bracket ("]")
  • Left square bracket ("[")
  • 'Pound' character ("#")
  • Non-printable ASCII characters (128–255 decimal characters)
  • Percent character ("%")
  • Quotation marks
  • Tilde ("~")
  • Vertical bar / pipe ("|")

The only restrictions provided by Amazon is (as found on their Technical FAQ):

What characters are allowed in a bucket or object name?
A key is a sequence of Unicode characters whose UTF-8 encoding is at most 1024 bytes long.

Additional restrictions apply for Buckets (as found on the Rules for Bucket Naming section of their Bucket Restrictions and Limitations FAQ):

In all regions except for the US Standard region a bucket name must comply with the following rules. These result in a DNS compliant bucket name.

  • Bucket names must be at least 3 and no more than 63 characters long
  • Bucket name must be a series of one or more labels separated by a period (.), where each label:
    • Must start with a lowercase letter or a number
    • Must end with a lowercase letter or a number
    • Can contain lowercase letters, numbers and dashes
  • Bucket names must not be formatted as an IP address (e.g., 192.168.5.4)

Less permissive restrictions apply to the US standard region. Please see the FAQs for additional information and some examples. Hope it helps!