File Storage Quickstart

The file storage module provides an easy way to securely share files between your users using access control lists. Selfbits uses Amazon's Simple Storage Service (S3) to guarantee reliable and failsafe file access. The file storage module is NOT designed for public file hosting.

A. Upload

If you want to upload a file you can use the REST-API or one of our SDK's. The file upload is a three step process that is initiated for one of your app users (f.e. user id 12345 and its jwt token ey123.xyz.abc)

1. Request to upload a file

This is the request to upload an arbitrarily named file to '12345/examplefolder/me.png'. The final filename will be me.png.

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ey123.xyz.abc" \
-H "sb-app-id: YOUR_APP_ID" \
-H "sb-app-secret: YOUR_APP_SECRET" \
-d '{ \
  "filePath": "examplefolder/me.png", \
  "permissionScope": "user" \
}' "https://YOURPROJECT-api.selfbits.io/api/v1/file"
Example response:
{
  "fileId": "586a1f8a1090127b2a050440",
  "putFileUrl": "https://s3.eu-central-1.amazonaws.com/files.selfbits.io/YOURPROJECT-api/12345/examplefolder/me.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIM53M5W6KLGW2MJQ%2F20170102%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20170102T093818Z&X-Amz-Expires=900&X-Amz-Signature=10c97d57dbe8a623f5ff89ffe34a637567c4da987873b588c5e3e2fa47fcb45e&X-Amz-SignedHeaders=host",
  "postVerifyUploadUrl": "https://YOURPROJECT-api.selfbits.io/api/v1/file/586a1f8a1090127b2a050440/verify",
  "expiresAt": 1483350798
}

The **fileId** is the unique identifier for the file and its metadata.
**putFileUrl** is the signed url where you have to upload your file in the second step.
**postVerfiyUploadUrl** is the endpoint to verify that your successful file upload (third step).
The **expiresAt** timestamp defines the expiry time of the signed putFileUrl link.

2. Execute the upload

curl -X PUT \
-F "data=@/home/user/Desktop/mypicture.png" \
"https://s3.eu-central-1.amazonaws.com/files.selfbits.io/YOURPROJECT-api/12345/examplefolder/me.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIM53M5W6KLGW2MJQ%2F20170102%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20170102T093818Z&X-Amz-Expires=900&X-Amz-Signature=10c97d57dbe8a623f5ff89ffe34a637567c4da987873b588c5e3e2fa47fcb45e&X-Amz-SignedHeaders=host"

If the upload is successful, you will receive http status code 200 and an ETag response header like ETag: "e10359a0e14135cb618a1a1ab9d0cfc1". This ETag is used to verify the upload.

3. Verify the upload

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ey123.xyz.abc" \
-H "sb-app-id: YOUR_APP_ID" \
-H "sb-app-secret: YOUR_APP_SECRET" \
-d '{
  "etag": "\"e10359a0e14135cb618a1a1ab9d0cfc1\""
}' "https://YOURPROJECT-api.selfbits.io/api/v1/file/586a1f8a1090127b2a050440/verify"
Example response:
{
  "_id": "586a1f8a1090127b2a050440",
  "__updatedAt": "2017-01-02T10:23:11.422Z",
  "__createdAt": "2017-01-02T10:01:05.163Z",
  "filePath": "examplefolder/me.png",
  "key": "YOURPROJECT-api/12345/examplefolder/me.png",
  "creator": "12345",
  "project": "YOURPROJECT-api",
  "__v": 0,
  "meta": {
    "LastModified": "Mon, 02 Jan 2017 10:02:08 GMT",
    "ContentLength": "552654",
    "ContentType": "binary/octet-stream"
  },
  "acl": [
    {
      "scope": "user",
      "identifier": "12345"
    }
  ],
  "verified": true,
  "permissionScope": "user",
  "etag": "\"e10359a0e14135cb618a1a1ab9d0cfc1\""
}

B. Sharing

A user can share its uploaded files with other users by adding their userIds to the access control list. A file can also be shared by adding a role to the access control list. Every user with the specified role will be able to access the file.

Giving other users access to a file

Share the file 586a1f8a1090127b2a050440 with user 5555

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ey123.xyz.abc" \
-H "sb-app-id: YOUR_APP_ID" \
-H "sb-app-secret: YOUR_APP_SECRET" \
"https://YOURPROJECT-api.selfbits.io/api/v1/file/586a1f8a1090127b2a050440/acl/user/5555"
Example response:
{
  "_id": "586a1f8a1090127b2a050440",
  "__updatedAt": "2017-01-02T10:23:11.422Z",
  "__createdAt": "2017-01-02T10:01:05.163Z",
  "filePath": "examplefolder/me.png",
  "key": "YOURPROJECT-api/12345/examplefolder/me.png",
  "creator": "12345",
  "project": "YOURPROJECT-api",
  "__v": 0,
  "meta": {
    "LastModified": "Mon, 02 Jan 2017 10:02:08 GMT",
    "ContentLength": "552654",
    "ContentType": "binary/octet-stream"
  },
  "acl": [
    {
      "scope": "user",
      "identifier": "12345"
    },
    {
      "scope": "user",
      "identifier": "5555"
    }
  ],
  "verified": true,
  "permissionScope": "user",
  "etag": "\"e10359a0e14135cb618a1a1ab9d0cfc1\""
}

Share the file 586a1f8a1090127b2a050440 with all users belonging to role user

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer ey123.xyz.abc" \
-H "sb-app-id: YOUR_APP_ID" \
-H "sb-app-secret: YOUR_APP_SECRET" \
"https://YOURPROJECT-api.selfbits.io/api/v1/file/586a1f8a1090127b2a050440/acl/role/user"
Example response:
{
  "_id": "586a1f8a1090127b2a050440",
  "__updatedAt": "2017-01-02T10:23:11.422Z",
  "__createdAt": "2017-01-02T10:01:05.163Z",
  "filePath": "examplefolder/me.png",
  "key": "YOURPROJECT-api/12345/examplefolder/me.png",
  "creator": "12345",
  "project": "YOURPROJECT-api",
  "__v": 0,
  "meta": {
    "LastModified": "Mon, 02 Jan 2017 10:02:08 GMT",
    "ContentLength": "552654",
    "ContentType": "binary/octet-stream"
  },
  "acl": [
    {
      "scope": "user",
      "identifier": "12345"
    },
    {
      "scope": "user",
      "identifier": "5555"
    },
    {
      "scope": "role",
      "identifier": "user"
    }
  ],
  "verified": true,
  "permissionScope": "user",
  "etag": "\"e10359a0e14135cb618a1a1ab9d0cfc1\""
}

C. Download

A user that has the right to access a file can request the file metadata containing a temporary download url. The download link can be used from anyone so it is also possible to only share this link. The optional expiresInSeconds query parameter allows to define the expiration time of the download link. If expiration is not set, the expiresInSeconds defaults to 900 (15 minutes).

curl -X GET -H "Content-Type: application/json" \
-H "Authorization: Bearer ey123.xyz.abc" \
-H "sb-app-id: YOUR_APP_ID" \
-H "sb-app-secret: YOUR_APP_SECRET" \
"https://YOURPROJECT-api.selfbits.io/api/v1/file/586a1f8a1090127b2a050440?expiresInSeconds=900"
Example response:
{
  "_id": "586a1f8a1090127b2a050440",
  "__updatedAt": "2017-01-02T10:23:11.422Z",
  "__createdAt": "2017-01-02T10:01:05.163Z",
  "filePath": "examplefolder/me.png",
  "key": "YOURPROJECT-api/12345/examplefolder/me.png",
  "creator": "12345",
  "project": "YOURPROJECT-api",
  "__v": 0,
  "meta": {
    "LastModified": "Mon, 02 Jan 2017 10:02:08 GMT",
    "ContentLength": "552654",
    "ContentType": "binary/octet-stream"
  },
  "acl": [
    {
      "scope": "user",
      "identifier": "12345"
    },
    {
      "scope": "user",
      "identifier": "5555"
    },
    {
      "scope": "role",
      "identifier": "user"
    }
  ],
  "verified": true,
  "permissionScope": "user",
  "etag": "\"e10359a0e14135cb618a1a1ab9d0cfc1\"",
  "url": "https://s3.eu-central-1.amazonaws.com/files.selfbits.io/YOURPROJECT-api/12345/examplefolder/me.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIM53M5W6KLGW2MJQ%2F20170102%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Date=20170102T104317Z&X-Amz-Expires=900&X-Amz-Signature=9ae6a1fb5f45fca9e5da88a97d9a1cb2875a9c2f7c777125c7fa135b5c73e7d8&X-Amz-SignedHeaders=host",
  "expiresAt": 1483354697
}

The url is a signed download url that is valid until expiresAt is reached.