Authentication

How to authenticate to the Meshes API using short-lived HS256 JWTs for machine-to-machine access, including required claims and Node.js examples.

Meshes API implements JSON Web Tokens (JWT) for server-side authentication. It is recommended you use one of the existing JWT libraries to generate the token rather than building the signature manually.

Authenticated requests must include the JWT in the HTTP Authorization header using the Bearer scheme:

Authorization: Bearer <jwt_token>

Generating Token

You can find more details and specifics about JWT at jwt.io. Below is a description of the minimum required fields for a Meshes machine access token.

alg – algorithm used. Meshes uses HMAC SHA-256 (HS256).
typ – token type. Always "JWT".
kid – key ID. This must be the access key for your Meshes machine key.

{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "<ACCESS_KEY>"
}

Payload

iss – issuer. Must be urn:meshes:m2m:<ACCESS_KEY>.
aud – audience. Must be "meshes-api".
org – the Organization ID (UUID) the request applies to.
iat – time the token was issued (seconds since Unix epoch, UTC).
exp – expiration time (seconds since Unix epoch, UTC). The maximum expiration time is 60 seconds.

{
    "iss": "urn:meshes:m2m:<ACCESS_KEY>",
    "aud": 'meshes-api',
    "org": '<ORG_UUID>',
    "iat": 1546289981
    "exp": 1546289986
}

Signature

Conceptually, the signature is generated as:

HMACSHA256(
  base64UrlEncode(header) + '.' + base64UrlEncode(payload),
  access_key_secret
);

However, you should not implement this manually. Use a JWT library.

Node.js Library example (jsonwebtoken)

const jwt = require('jsonwebtoken');

const accessKey = process.env.MESHES_ACCESS_KEY;
const secretKey = process.env.MESHES_SECRET_KEY;
const organizationId = process.env.MESHES_ORG_ID;

const now = Math.floor(Date.now() / 1000);

const payload = {
  iss: `urn:meshes:m2m:${accessKey}`,
  aud: 'meshes-api',
  org: organizationId,
  iat: now, // time issued
  exp: now + 30, // 30 seconds
};

const token = jwt.sign(payload, secretKey, {
  algorithm: 'HS256',
  header: {
    kid: accessKey,
    typ: 'JWT',
  },
});

Node.js Example (jose)

import { SignJWT } from 'jose';

const accessKey = process.env.MESHES_ACCESS_KEY!;
const secretKey = process.env.MESHES_SECRET_KEY!;
const organizationId = process.env.MESHES_ORG_ID!;

// jose requires a Uint8Array for symmetric HS256 keys
const key = new TextEncoder().encode(secretKey);

export async function createMeshesMachineToken() {
  const token = await new SignJWT({
    org: organizationId
  })
    .setProtectedHeader({
      alg: 'HS256',
      typ: 'JWT',
      kid: accessKey
    })
    .setIssuer(`urn:meshes:m2m:${accessKey}`)
    .setAudience('meshes-api')
    .setIssuedAt() // automatically sets iat (seconds)
    .setExpirationTime('30s') // must be <= 60s
    .sign(key);

  return token;
}

Node.js Example (Meshes API client)

import MeshesApiClient from "@mesheshq/api";

const accessKey = process.env.MESHES_ACCESS_KEY!;
const secretKey = process.env.MESHES_SECRET_KEY!;
const organizationId = process.env.MESHES_ORG_ID!;

const client = new MeshesApiClient(organizationId, accessKey, secretKey);

try {
  const workspaces = await client.get("/workspaces");
  // success handling
} catch (err) {
  // error handling
}