Authentication

With the ConnectIt+ API, there are two types of authentication tokens:

• Developer Key
• Plugin Installation JWT

In the API reference, each endpoint will declare which type of token is required to access it.

Developer Key

A Developer Key is used to authenticate requests to the ConnectIt+ API. This key is generated in the Developer Portal. You can use this key to create Plugins and to manage your Developer Account.

To sign a request using a Developer Key, you'll need to include the token in the Authorization header:

curl -H "Authorization: Bearer DEVELOPER_KEY" \
     -H "Content-Type: application/json" \
     https://api.mobileassistant.us/plugins

Plugin Installation JWT

A Plugin Installation JWT is a JSON Web Token that is used to authenticate requests to the ConnectIt+ API and to access data on behalf of a user. The Plugin Installation JWT needs to be generated by you and expires after 1 hour. In order to generate a Plugin Installation JWT, you'll need a Plugin Installation UUID and a Plugin Secret Key.

Here's an example of how to create the Plugin Installation JWT using JavaScript or Python (and how to access the variables used for creation):

JavaScript

import * as jose from 'jose'; // npm install jose

const encodedPluginSecretKey = new TextEncoder().encode('PLUGIN_SECRET_KEY');

const PLUGIN_INSTALLATION_JWT = new jose.SignJWT({
  iat: Math.floor(Date.now() / 1000),
  exp: Math.floor(Date.now() / 1000) + (60 * 60),
  plugin_installation_uuid: 'PLUGIN_INSTALLATION_UUID'
}).setProtectedHeader({alg: 'HS256'}).sign(encodedPluginSecretKey);

// This is a Plugin Installation JWT, and you'll need this to sign requests to the API on behalf of the user
console.log(PLUGIN_INSTALLATION_JWT);

Python

import jwt # pip install pyjwt
import time

PLUGIN_INSTALLATION_JWT = jwt.encode({
    'iat': int(time.time()),
    'exp': int(time.time()) + (60 * 60),
    'plugin_installation_uuid': 'PLUGIN_INSTALLATION_UUID',
}, 'PLUGIN_SECRET_KEY', algorithm='HS256')

# This is a Plugin Installation JWT, and you'll need this to sign requests to the API on behalf of the user
print(PLUGIN_INSTALLATION_JWT)

More details on the variables used to create this token:

• PLUGIN_INSTALLATION_UUID: In order to generate a Plugin Installation JWT, you'll need to know the Plugin Installation UUID of the user you are trying to access data for. You can find this UUID in the Developer Portal during testing or use the Plugin Installation API to retrieve it in production.

• PLUGIN_SECRET_KEY: You will also need a Plugin Secret Key to sign this JWT so that we can verify this is a valid token. Refer to the Plugin API to learn how to generate a Plugin Secret Key. A Plugin Secret Key is unique to each plugin and should be kept secret. It will start with a sk_live_ prefix.

To sign a request using a Plugin Installation JWT, you'll need to include the token in the Authorization header:

curl -H "Authorization: Bearer PLUGIN_INSTALLATION_JWT" \
     -H "Content-Type: application/json" \
     https://api.mobileassistant.us/users/me