# Getting Started

TL;DR: Already have Parcel installed? Skip to Uploading Data.

# Setup

To integrate with Parcel in your application, you can either use our TypeScript client or hit our REST APIs directly. For modern JavaScript or TypeScript projects, we recommend you use our client library. For other projects, you'll need to work directly with our REST APIs. We hope to roll out client libraries for other platforms in the future.

# Parcel TypeScript Client

Our Parcel TypeScript client targets modern JavaScript. For server-side applications, you need to run Node.js 14 or newer. Please refer to the Node.js website (opens new window) for the installation method most suitable for your platform.

# Parcel REST API

While these tutorials focus on using our TypeScript client, you can also make calls directly to our REST API with your developer credentials. You can view the full list of supported endpoints with our Parcel API reference.

# Install

You can install the TypeScript client package (opens new window) with:

npm install @oasislabs/parcel

Now you're ready to use the client within a TypeScript project:

import Parcel from "@oasislabs/parcel"

If you're writing your application in JavaScript, be sure your package.json file enabled ES modules (opens new window):

{
  "type": "module",
}

# Authentication

In order to use Parcel services, you will need to register your application with us, as well as one or more clients for your application. We support two types of client authentication:

  • Server-side clients authenticate using public-private keypairs. You should use server-side clients wherever it's safe to store a private key. For example, you might register a server-side client for a backend Node server or a set of serverless functions.

  • Frontend clients authenticate via OAuth2 using a client ID and redirect URL pair. You should use frontend clients when it's not possible to safely store a private key. For example, you might register a frontend client for your web or mobile app.

You may register one or more clients for your application. For example, if you are building a photo sharing application, you might register one application and three associated clients:

|- Application: My Photo App
   |- Frontend client: Web client
   |- Frontend client: iOS client
   |- Server-side client: Severless backend functions

# Generating keypairs

For server-side clients, where it is safe to store a private key, you will need to generate a P256 ECDSA keypair in JSON Web Key (JWK) (opens new window) format.

Your keypair will have two parts, the public key and the private key. Your public key is safe to share and you will register that with us in our developer portal. Your private key is sensitive and should never be shared. Oasis Labs does not need and will never ask for your private key.

You can recognize a private key by a d field. A public key does not have it.

Here are a few common ways to generate keypairs:

# Python

To generate a keypair in Python, you can use the jwcrypto library. The following commands will generate and print a public-private keypair:

  $ pip3 install jwcrypto
  $ python3 -c "from jwcrypto import jwk; key = jwk.JWK.generate(kty='EC', crv='P-256'); print(key.export(private_key=False)); print(key.export())"
  {"crv":"P-256","kty":"EC","x":"qyea2InZ9rA-vwFdXLS5GFyqgqXwZOtGK1FPKxCLHqk","y":"MYWKhXtoVuDbukTo7qfXzlIDshi1SeojNQ3HSz117O8"}
  {"crv":"P-256","d":"9RiQC1F6al90dbqs4iDpiOkpJIpnlYJZ4i474qzH6Ns","kty":"EC","x":"qyea2InZ9rA-vwFdXLS5GFyqgqXwZOtGK1FPKxCLHqk","y":"MYWKhXtoVuDbukTo7qfXzlIDshi1SeojNQ3HSz117O8"}

The first printed line is your public key and the second printed line is your private key.

# Golang

To generate a keypair in Golang, you can use the jwk-keygen library. The following commands will generate and print a public-private keypair:

  $ go get -u gopkg.in/square/go-jose.v2/jwk-keygen
  $ $GOPATH/bin/jwk-keygen --alg=ES256 --use=sig
  ==> jwk_ES256.pub <==
  {"use":"sig","kty":"EC","crv":"P-256","alg":"ES256","x":"qyea2InZ9rA-vwFdXLS5GFyqgqXwZOtGK1FPKxCLHqk","y":"MYWKhXtoVuDbukTo7qfXzlIDshi1SeojNQ3HSz117O8"}
  ==> jwk_ES256 <==
  {"use":"sig","kty":"EC","crv":"P-256","alg":"ES256","x":"qyea2InZ9rA-vwFdXLS5GFyqgqXwZOtGK1FPKxCLHqk","y":"MYWKhXtoVuDbukTo7qfXzlIDshi1SeojNQ3HSz117O8","d":"9RiQC1F6al90dbqs4iDpiOkpJIpnlYJZ4i474qzH6Ns"}

The line following ==> jwk_ES256.pub <== is your public key, as denoted by the .pub extension. The line following ==> jwk_ES256 <== is your private key.

# Web

If you have trouble getting the tools above to work, or if you just want a quick key to test out Parcel, you can also generate a key at mkjwk.org (opens new window). Select the EC tab and choose curve=P-256, keyUse=Signature, algorithm=ES256.

WARNING

This site is useful for quickly generating keys so you can start testing out Parcel. However, when you're ready to ship your integration to production and start handling sensitive data, we strongly recommend generating your keypairs yourself (see Python or Go methods) so you can ensure no one else has access to your private key.

# Registering credentials

Once you've generated your keypair, you'll need to register it in our developer portal before you use it with our client library or API.

To register your credentials with us:

  1. Log in to the Parcel developer portal (opens new window).

  2. Click on Create my app (opens new window).

  3. Fill in basic information about your app.

  4. Add a permission to your app. This will be shown to new users when your app requests permissions to use their data.

  5. Click Create client from your app's info page.

  6. Select the Server-side type for your new client.

  7. Paste in the public key you generated above. Note: the public key, which is safe to share with us, does not contain a d key in its JSON body.

  8. Click Create client to save your credentials.

  9. You should now see a client ID for the client you just registered. Make sure to save this for use with the SDK later.

WARNING

Never share your private keys with us, or anyone else. If you believe your private key has been improperly shared, please delete the associated client from our developer portal, generate a new keypair, register the new public key, and use the new private key.

# Using credentials

Now that our credentials are registered, we are ready to start using the SDK!

It's as simple as importing the Parcel client:

import Parcel from "@oasislabs/parcel";

Pulling in our client ID and private key:

// e.g. "IPoxXkdvFsrqzDdU7h3QqSs"
const clientId = process.env.PARCEL_CLIENT_ID ?? '';
// e.g. "{kty:'EC',alg:'ES256',use:'sig',crv:...}"
const privateKey = JSON.parse(process.env.PARCEL_PRIVATE_KEY ?? '');

Assuming you've exported your client ID (provided to you in the developer portal) and your private key as environment variables.

And creating a new Parcel instance with our credentials:

const parcel = new Parcel({
  clientId: clientId,
  privateKey: privateKey
});

You should now be able to use your parcel instance to interact with Parcel services. You can confirm by calling:

const myIdentity = await parcel.getCurrentIdentity();
console.log(myIdentity.id);

Which yields the client ID for your application:

IPoxXkdvFsrqzDdU7h3QqSs

# Next Steps

Nice work! You're ready to start using Parcel in your application.

The following tutorials will walk you through storing data, managing access, and running confidential computations so you can build great features for your customers while keeping their data private and secure.