Skip to main content
POST
/
resources
/
buckets
Create bucket
curl --request POST \
  --url https://api-dev.narrative.io/resources/buckets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": 12345678901,
  "resource_id": "yourcompany",
  "access": {
    "type": "role",
    "external_id": "22a7553b-9240-4b81-93ae-54ccbcde0a8"
  }
}
'
{
  "id": "45b40bf5-02fc-4f18-bfcd-50ac58dabfa1",
  "company_id": 1,
  "auth": {
    "type": "bucket_policy",
    "account_id": "123456789012"
  },
  "name": "nio-yourcompany-821627dd2931",
  "created_at": "2021-08-31T20:22:02Z",
  "updated_at": "2021-08-31T20:22:02Z"
}

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.
Example:

12345678901

​
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 at least 2 and less than 43 characters long
Example:

"yourcompany"

​
access
object
Example:
{
  "type": "role",
  "external_id": "22a7553b-9240-4b81-93ae-54ccbcde0a8"
}

Response

200 - application/json

OK

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

​
id
string

Unique identifier for the bucket.

Example:

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

​
auth
object
​
company_id
integer

The ID of the company owning the bucket.

​
name
string

The AWS S3 bucket name. The bucket name is of the form nio-${resource_id}-${suffix} where resouce_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

ISO-8601 timestamp indicating when the bucket was created.

Example:

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

​
updated_at
string

ISO-8601 timestamp indicating when the bucket was last updated.

Example:

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

​
is_access_mutable
boolean

Is it allowed to change access type. Changes are allowed by default. Restrictions could be applied in case bucket was manually config