Portive

Authentication

API Key

You can get a free API key from the Portive website.

It's not necessary to understand the internals of an API Key to use one. This documentation is provided for contributors and those that are interested.

An API key is a string made up of three parts separated by underscores and looks something like:

PRTV_y3txuDV2lnxv7onl_ZApfHvVyHVUGvB84bDgxkE2OZAia2zCk

Inside an API Key

Parts of an API Key

API keys are made up of these three parts separated by underscores:

  1. Key Type - Always PRTV
  2. Key Id - Public part of an API Key
  3. Secret Key - Private part of an API Key

1. API Key Type

The first part, the Key Type, is always PRTV to make it easily identifiable as a Portive API key

2. API Key ID

The second part, the API Key ID is a string that uniquely identifies the API key. This value is not a secret and is made up of uppercase/lowercase alphanumeric characters. It is delivered in the open as part of any generated authToken.

3. API Secret Key

The third part, the API Secret key, is used to encrypt auth tokens. It is not delivered in the open as part of an authToken.

The Underscore Separator

As part of its design, the API Key uses underscore as a separator between each part of the API Key.

This character was chosen to make the key easier to select for copy and paste. Double-clicking on an API key in text selects the entire key because the underscore is not considered a word delimiter whereas other characters like a dash are. A . was not selected to disambiguate it from a JSON Web Token which is the format of an Auth Token.

Static Methods

stringifyApiKey

stringifyApiKey({ keyId: string, secretKey: string }) => string

Takes the keyId of an API key and the secretKey of an API key and turns it into an API key.

This method is necessary because the API Key is not stored as a single value anywhere and the secretKey is always encrypted at rest. This method is used to stitch the values back together.

Example:

const apiKey = stringifyApiKey({
  keyId: "y3txuDV2lnxv7onl",
  secretKey: "ZApfHvVyHVUGvB84bDgxkE2OZAia2zCk",
})
// => "PRTV_y3txuDV2lnxv7onl_ZApfHvVyHVUGvB84bDgxkE2OZAia2zCk"

parseApiKey

parseApiKey(apiKey: string) => {
  keyType: string
  keyId: string
  secretKey: string
}

Takes an API key in the form of a single string and breaks it into its separate parts.

Note that the keyType should alays be PRTV

Example:

const apiKeyInfo = parseApiKey(
  "PRTV_y3txuDV2lnxv7onl_ZApfHvVyHVUGvB84bDgxkE2OZAia2zCk"
)

// => {
//   keyType: "PRTV",
//   keyId: "y3txuDV2lnxv7onl",
//   secretKey: "ZApfHvVyHVUGvB84bDgxkE2OZAia2zCk",
// })