Authentication

Introduction to Authentication

When using Portive Cloud enabled components like Plate Cloud or Slate Cloud, you must provide either an apiKey or an authToken.

For example, in Plate Cloud, it looks something like this:

// with an API key
createCloudPlugin({
  options: {
    apiKey: "PRTV_xxxxxx_xxxxxx",
  },
})

// with an Auth Token
createCloudPlugin({
  options: {
    authToken: "xxxxxxxxxxxxxxxx",
  },
})

This introduction to authentication will show you when to use an API Key and when to use the Auth Token and how to create one.

API Key vs Auth Token

Should you use an API key or an Auth Token?

API Key: If you are getting started, in development mode or trying Portive out, you can start with an API key. It's faster and easier to get started.
Auth Token: If you are in production, need higher security or you need access to features only available with Auth Tokens then use an Auth Token. This requires you to generate auth tokens on the server takes a little more work.

API Keys

Getting and using an API Key

The easiest way to get started is to get a Portive API key and use it with any Portive Cloud enabled rich text editor.

Getting an API key is easy and takes less than a minute.

Once you have an API key, you can plug it into any Portive Cloud enabled rich text editor like Plate, Slate or Wysimark.

// not actual code...
createCloudPlugin({
  options: {
    apiKey: "PRTV_xxxxxx_xxxxxx",
  },
})

Auth Tokens

About Using Auth Tokens

Instead of passing your API Key directly to your component, you can generate an authToken from your API key and use that instead.

There are benefits to generating and using an authToken instead of using your API key directly such as:

It hides your API keys: You aren't passing your API key in the open so it remains a secret. The authToken is designed so that the API Key cannot be extracted from it.
Auth tokens expire: Your authToken has an expiry time which you specify which prevents a user from using an authToken past the time the user is allowed to. This, along with the hiding of your API key, allows you to better control access to the cloud services.
Features: Certain features like tagging uploads and limiting uploads per user or per project can only be done using an authToken

Generating Auth Tokens

Auth tokens should be generated on the server only. This is because we use the API Key to generate an Auth Token and we don't want that API key on the browser.

If you are using Next.js, you can skip to the Next.js Guide for Auth which provides specific instructions for Next.js.

First, install @portive/auth:

# yarn
yarn add @portive/auth

# npm
npm install --save @portive/auth

To create the Auth Token in JavaScript on the server you would use code like below.

We are assuming for this example that process.env.API_KEY is set to a Portive API Key.

JavaScript
import { createAuthToken } from "@portive/auth"

const authToken = createAuthToken(process.env.API_KEY, {
  expiresIn: "24h",
})

console.log(authToken)

In a real web application, the authToken would not be created in the main body of the JavaScript file as shown.

It would be generated in the code for an API endpoint and returned to the user after some authentication.

Let's assume that you create an API endpoint for your application at "/api/get-auth" that returns the Auth Token as { authToken: "xxxx" }.

In order to get the auth token, we can use an async function that returns an authToken as the value for the authToken option. It might look something like the following example.

createCloudPlugin({
  options: {
    authToken: async () => {
      const response = await fetch("https://mysite.com/api/get-auth", {
        method: "POST",
      })
      const json = await response.json()
      return json.authToken
    },
  },
})

The example makes a POST request to https://mysite.com/api/get-auth, parses the response as JSON, and takes the authToken from the response.