IAM Client

The @justrelate/iam-client library provides a simple and secure way to authenticate users via the JustRelate IAM service. It validates IAM tokens and retrieves user details for authorized services.

⚠️ Internal Use Only:
This library is intended for internal use only. It contains internal APIs and must not be used outside of JustRelate.

Installation

npm install @justrelate/iam-client

Quick Start

Authenticate a user with their IAM token:

import { authenticate } from '@justrelate/iam-client';

const result = await authenticate({
  instanceId: 'your-instance-id',
  authToken: 'your-bearer-token',
  service: 'https://api.justrelate.com/your-service',
});

if ('error' in result) {
  console.error('Authentication failed:', result.errorResponse);
} else {
  console.log('Authenticated user:', result.name);
}

API Reference

authenticate(params: AuthenticateParams): Promise<IAMAuthResponse>

Validates an IAM token using the JustRelate IAM service.

Parameters

| Name | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------ | | authToken | String | Yes | The IAM bearer token used for authentication | | instanceId | String | Yes | The unique identifier of your JustRelate instance | | service | String | Yes | The URL of the service the token should authenticate (e.g., https://api.justrelate.com/your-service) | | baseAuthUrl | String | No | Custom IAM base URL (defaults to https://api.justrelate.com/iam/) |

Returns

A promise that resolves to one of the following:

Success (IAMAuthSuccess)

{
  account_id: string;
  email: string;
  name: string;
  picture: string;
  sub: string;
  team_ids: string[];
}

Failure (IAMAuthFailure)

{
  status: number;
  errorResponse: {
    error: string;
    code?: string;
    details?: object;
  };
}

Status Codes

• 401 – Invalid authentication token
• 403 – Insufficient permissions
• 404 – Invalid instance ID

Exceptions

The authenticate function may throw an IAMAuthError if:

• The IAM service does not respond within 10 seconds
• There are network issues (e.g., DNS, CORS, blocked requests)
• The response has an unexpected status code
• The response body is not valid JSON

Usage Examples

Basic Authentication

import { authenticate } from '@justrelate/iam-client';

try {
  const result = await authenticate({
    instanceId: 'your-instance-id',
    authToken: 'your-token-here',
    service: 'https://api.justrelate.com/your-service',
  });

  if ('error' in result) {
    console.error('Auth failed:', result.errorResponse);
  } else {
    console.log('Welcome,', result.name);
    console.log('Team IDs:', result.team_ids);
  }
} catch (error) {
  console.error('Authentication error:', error.message);
}

Express.js Middleware

Integrate IAM authentication into your Express.js application:

import express from 'express';
import { authenticate } from '@justrelate/iam-client';

export async function withIAMAuth(req, res, next) {
  try {
    const token = req.headers.authorization?.replace('Bearer ', '') || '';

    const currentUser = await authenticate({
      instanceId: req.params.instanceId,
      authToken: token,
      service: 'https://api.justrelate.com/your-service',
    });

    if ('errorResponse' in currentUser) {
      return res.status(currentUser.status).json(currentUser.errorResponse);
    }

    res.locals.currentUser = currentUser;
    return next();
  } catch (error) {
    return res.status(500).json({ error: 'Internal Server Error' });
  }
}

const app = express();

app.get('/', (req, res) => {
  res.send('Hello from Express!');
});

app.get('/:instanceId/current-user', withIAMAuth, (req, res) => {
  res.json({ currentUser: res.locals.currentUser });
});

app.listen(3000, () => {
  console.log('Server is running at http://localhost:3000');
});

Testing the Endpoint

Use curl to test the protected route:

curl -X GET "http://localhost:3000/YOUR_INSTANCE_ID/current-user" \
     -H "Authorization: Bearer YOUR_TOKEN"

Available Routes:

• GET / — Public endpoint
• GET /:instanceId/current-user — Protected IAM-authenticated endpoint

License

UNLICENSED

Support

For help or questions, please contact the Scrivito team via the #dev-scrivito Slack channel.