An Access Grant is a security envelope that contains a satellite address, a restricted API Key, and a restricted path-based encryption key - everything an application needs to locate an object on the network, access that object, and decrypt it.
Learn more about Access Management and Access Grants or check out the FAQ on Access Grants and Encryption Keys.
The Access Grant screen allows you to create or delete Access Grants, generate credentials for the Storj DCS S3-compatible Gateway from an Access Grant, create an API key to generate an access grant in the CLI.
Create Access Grant #
Let’s start with creating an Access Grant. Click the Create Access Grant Button.
Give your Access Grant a name:
Set any access restrictions you want encoded into your Access Grant. Through the Satellite Admin Console, you can set basic restrictions on your Access Grant. You can get more sophisticated using the CLI and add further, more granular restrictions, for example, at the path prefix level within a Bucket.
Next, enter an Encryption Passphrase for your Access Grant. Note that this encryption passphrase is handled by the browser and is not stored by the Satellite. You can either Generate Passphrase or Create My Own Passphrase.
Do not lose your Encryption Passphrase. Storj DCS does not manage your encryption keys and if you lose your Encryption Passphrase and your Access Grant, you will not be able to decrypt your data.
Copy or download your Access Grant. Do not lose it, you only have one opportunity to do so. If you did not save it, please delete this Access Grant and create a new one and save it on this time.
This Access Grant can now be used to configure tools like the Storj DCS Uplink CLI, libuplink library, or apps like Rclone, FileZilla or Restic. You can also generate credentials for the Storj DCS S3-compatible Gateway.
Create S3 Credentials #
Remember, when you generate credentials for the Storj DCS S3-compatible Gateway from an Access Grant, you are opting in to server-side encryption.
When you generate credentials for the Storj DCS S3-compatible Gateway, the Admin Console will create and register your Access Grant with the Gateway auth service and display the credentials required to configure your client app to work with the Storj DCS S3-compatible Gateway.
Create Keys for CLI #
- You need to have a satellite account and installed Uplink CLI.
- To start, proceed through the initial steps of creating a new Access Grant.
- Navigate to Access page and click the Create Keys for CLI link (rightmost option).
4. Provide name, permissions and optionally buckets, select Create Keys.
5. Copy and save the Satellite Address and API Key in a safe place or download them as they will only appear once.
6. Make sure you’ve already
downloaded the Uplink CLI and run
For anyone who has previously configured an Uplink, please use a named access. If you want to replace the default access, you need to either Create an Access Grant and use the
uplink access importcommand with
--forceflag to import it, or use the
uplink access create --import-to <name>command with
--forceflag to create an Access Grant in CLI and import it to the specified access in the local store of Uplink.
7. Follow the prompts. When asked for your API Key, enter it (you should have saved it in step 5 above).
8. Generate the Access Grant by running
uplink share with no restrictions.
If you chose an access name, you’ll need to specify it in the following command as
./uplink.exe share --readonly=false
uplink share --readonly=false
uplink share --readonly=false
Keep your full-rights Access Grant secret, it contains the encryption key and will enable uploading, downloading or deleting your data from the entire project!
9. Your Access Grant should have been output.
The alternative for using the
uplink setupcommand and then
uplink shareis to use the
uplink access createcommand instead, it will print the Access Grant right away.
Delete Access Grant #
To Delete an Access Grant, select three dots on the right side of the Access Grant and choose Delete Access:
Then confirm that you want to delete the Access Grant by typing its name and confirming with Delete Access button.
Important: If you delete an Access Grant from the Satellite user interface, that Access Grant will immediately cease to function, and all hierarchically derived child Access Grants and Storj DCS gateway access credentials based on that Access Grant will also cease to function. Any data uploaded with that Access Grant will persist on Storj DCS. If you didn’t back up the Encryption Passphrase used with the Access Grant you are deleting, you will not be able to decrypt that data without that Encryption Passphrase, and it will be effectively unrecoverable.
You don’t need to know everything in the whitepaper about our Access Grants, macaroon-based API Keys or our encryption implementation, but if you understand the general principles, you’ll find these are some very sophisticated (but easy to use) tools for creating more secure and private applications.
Next we’ll cover adding and removing other developers to and from your project.