Skip to main content
POST
Create bucket

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
account_id
string
required

Your 12 digit AWS account ID. That ID will be used:

  • to enable root-based access in case of "bucket_policy" access type;
  • to create (or use existing) IAM Role that will be available for specified user.
Pattern: ^[0-9]{12}$
Example:

"012345678901"

resource_id
string
required

A short identifier that will be a part of your bucket's name.

A typical choice would be your company's name, lowercased and spaces replaced with -.

Resource IDs must:

  • consist of only lowercase alphanumeric characters or -
  • be from 2 to 44 characters long
Required string length: 2 - 44
Pattern: ^[a-z0-9-]+$
Example:

"yourcompany"

external_id
string | null

The external ID for the bucket's access role, read only when access is omitted or null. The bucket then gets role access, and the role requires this external ID if one is given. When access is set, this field is ignored and the external ID goes in access instead.

It follows the same rules as external_id in access.

Required string length: 2 - 1224
Example:

"22a7553b-9240-4b81-93ae-54ccbcde0a8"

access
object

How your AWS account reaches the bucket. When access is omitted or null, the bucket gets role access, using the top-level external_id.

Example:

Response

OK

An AWS S3 bucket created inside Narrative's AWS account assigned to a specific company.

id
string<uuid>
required

Unique identifier for the bucket.

Example:

"4d5451ff-5fe6-4db3-9398-4075bbd275b0"

auth
object
required

How your AWS account reaches the bucket. type is bucket_policy, role or user.

company_id
integer
required

The ID of the company owning the bucket.

name
string
required

The AWS S3 bucket name. The bucket name is of the form nio-${resource_id}-${suffix} where resource_id is the resource ID provided at bucket creation and suffix is 12 randomly chosen alphanumeric characters.

A random suffix is appended to the bucket name for two reasons:

  • AWS S3 bucket names must be globally unique, i.e. the bucket namespace is shared by all AWS accounts. Appending a random suffix helps ensure that we can create a bucket which includes your preferred resource ID.
  • Another consequence of AWS S3 bucket names needing to be globally unique is that anyone can easily check if a bucket with a given name exists. By appending a random suffix to your bucket we are preventing information leakage by making it impractical for an attacker to determine whether you are a customer of Narrative by simply guessing your resource ID and checking whether a bucket with the name nio-${resource_id} exists.
Example:

"nio-yourcompanyname-50ac58dabfa1"

created_at
string<date-time>
required

When the bucket was created.

Example:

"2021-08-26T21:06:07.710357Z"

updated_at
string<date-time>
required

When the bucket was last updated.

Example:

"2021-08-26T21:06:07.710357Z"

is_access_mutable
boolean
required

Whether POST /resources/update-access can change the bucket's access type. Buckets created through POST /resources/buckets can be changed. Some buckets created before 2023 with custom policies cannot.