Client library for TheAuthAPI

Contents

• Client library for TheAuthAPI
  • Installation
  • Configuration
    • Imports
      • CommonJS
      • ES Modules
  • Usage
    • Example: Validating an API-Key
    • Example: Listing API-keys
    • Example: Listing the projects of an account
    • Example: Listing projects and associated API-Keys
    • Example: Creating an API-Key
    • Example: Rotating an API-Key
    • Handling Errors
      • ApiRequestError
      • ApiResponseError
      • Example: Getting a key throws an ApiResponseError if the key is invalid
      • Error
      • Handling Errors the Right Way
    • Typescript
    • 📙 Further Reading

Scalable API Key Management and Auth Control Secure your API with best in class API Key management, user access, all with great analytics.

Installation

This library is published on npm, you can add it as a dependency using the following command

npm install theauthapi
# or
yarn add theauthapi

Configuration

You'll need to configure the library with your access key and account id, you can grab these from TheAuthAPI dashboard.

For further instructions on creating an account, check out our how to guides.

Imports

CommonJS

const TheAuthAPI = require('theauthapi');

ES Modules

import TheAuthAPI from 'theauthapi';

initialize the client using your access key:

const theAuthAPI = new TheAuthAPI('YOUR_ACCESS_KEY');

You can also provide custom options:

const theAuthAPI = new TheAuthAPI('YOUR_ACCESS_KEY', {
  retryCount: 2,
});

Full option types:

type Options = {
  // server url
  host?: string;
  // number of retries before failing
  retryCount?: number;
};

Usage

After initiating the client, you can access endpoint methods using the following pattern: [object instance].[endpoint].[method]

For example, getting the projects for an account would be: theAuthApiClient.projects.getProjects("ACCOUNT_ID"),

Similarly, getting the api keys would be: theAuthApiClient.apiKeys.getKeys("PROJECT_ID")

| endpoint | attribute | example | | --------- | --------- | --------------------------------------------- | | /api-keys | apiKeys | client.apiKeys.createKey("MY_KEY") | | /projects | projects | client.projects.createProject("MY_PROJECT") | | /accounts | accounts | client.accounts.createAccount("MY_ACCOUNT") |

For details on each endpoint accepted values, please reference these docs: docs.theauthapi.com

All methods return a promise containing the returned JSON as a javascript object. Each method of an endpoint maps HTTP methods to

| HTTP Method | method name | example | | ----------- | ----------- | ------------------------------------------------------------------------- | | POST | create* | client.apiKeys.createKey({ name: "KEY_NAME", projectId: "PROJECT_ID" }) | | GET | get* | client.apiKeys.getKeys() | | DELETE | delete* | client.apiKeys.deleteKey("MY_KEY") | | PATCH | update* | client.apiKeys.updateKey("MY_KEY", { name: "UPDATED_KEY_NAME" }) |

Example: Validating an API-Key

You can easily validate an API key using apiKeys.isValidKey which returns true if the key is valid, false otherwise. isValidKey throws an ApiRequestError if there's a network issue, it's advised to wrap it in a try/catch to handle the potential error

theAuthAPI.apiKeys
  .isValidKey('API_KEY')
  .then((isValidKey) => {
    if (isValidKey) {
      console.log('The API is valid!');
    } else {
      console.log('Invalid API key!');
    }
  })
  .catch((error) => {
    // handle network error
  });

Using async/await

try {
  const isValidKey = await theAuthAPI.apiKeys.isValidKey('API_KEY');
  if (isValidKey) {
    console.log('The API is valid!');
  } else {
    console.log('Invalid API key!');
  }
} catch (error) {
  // handle network error
}

Note: If you want to consume the API key and get the API key entity in return, you can use apiKeys.authenticateKey which returns an ApiKey.

Example: Listing API-keys

theAuthAPI.apiKeys
  .getKeys()
  .then((keys) => console.log(keys))
  .catch((error) => console.log(error));

Using async/await

try {
  const keys = await theAuthAPI.apiKeys.getKeys();
} catch (error) {
  console.log(error);
}

Filtering API Keys: You can filter the listed API keys by passing an object of type filter as an argument to getKeys

type ApiKeyFilter = {
  projectId?: string;
  name?: string;
  customAccountId?: string | null;
  customUserId?: string | null;
  isActive?: boolean;
};

Example: filtering api-keys with a specific projectId where the keys are not active

try {
  const keys = await theAuthAPI.apiKeys.getKeys({
    projectId: 'PROJECT_ID',
    isActive: false,
  });
} catch (error) {
  console.log(error);
}

NOTE that if your access key is at account level, you need to specify projectId when listing the API keys: getKeys({ projectId: "PROJECT_ID" }), otherwise if your access key is created at project level, you don't have to specify projectId, the access key's projectId will be used to get the API-keys (i.e. you'll see only the keys of the project your access key is created against)

Example: Listing the projects of an account

theAuthAPI.projects
  .getProjects('ACCOUNT_ID')
  .then((projects) => console.log(projects))
  .catch((error) => console.log(error));

Using async/await

try {
  const projects = await client.projects.getProjects('ACCOUNT_ID');
} catch (error) {
  console.log(error);
}

Example: Listing projects and associated API-Keys

async function getProjectsWithKeys(accountId: string) {
  try {
    const projects = await theAuthAPI.projects.getProjects(accountId);
    const projectsKeys = projects.map(async (project) => {
      const keys = await theAuthAPI.apiKeys.getKeys(project.id);
      return { project, keys };
    });
    return await Promise.all(projectsKeys);
  } catch (error) {
    // handle error
  }
}

Example: Creating an API-Key

theAuthAPI.apiKeys
  .createKey({
    projectId: 'PROJECT_ID',
    customMetaData: { metadata_val: 'value to store' },
    customAccountId: '[any info you want]',
    name: '[any info you want e.g. name of customer or the key]',
  })
  .then((key) => console.log('Key created > ', key))
  .catch((error) => console.log("Couldn't make the key", error));

Using async/await

try {
  const key = await theAuthAPI.apiKeys.createKey({
    projectId: 'PROJECT_ID',
    customMetaData: { metadata_val: 'value to store' },
    customAccountId: '[any info you want]',
    name: '[any info you want e.g. name of customer or the key]',
  });
  console.log('Key created > ', key);
} catch (error) {
  console.log("Couldn't make the key ", error);
}

Example: Rotating an API-Key

When you need to quickly and securely rotate a compromised key, while preserving the key's metadata, use the rotateKey method. This method while clone your key and return you with a new one.

theAuthAPI.apiKeys
  .rotateKey('API_KEY')
  .then((key) => console.log('Rotated Key > ', key))
  .catch((error) => console.log("Couldn't rotate the key", error));

Using async/await

try {
  const key = await theAuthAPI.apiKeys.createKey('API_KEY');
  console.log('Rotated Key > ', key);
} catch (error) {
  console.log("Couldn't rotate the key", error);
}

NOTE In the background, this marks the old key as inactive and issues you with a new key. Any requests to the old key will be instantly blocked.

Handling Errors

ApiRequestError

Thrown when there's a network or a connectivity issue, for example, if the client didn't establish any network connection with the host

ApiRequestError: getaddrinfo EAI_AGAIN api.theauthapi.com

ApiResponseError

Thrown when the server responds with an HTTP status code not in the 2xx range. ApiRequestError provides two properties to distinguish the type of the error

• statusCode HTTP status code
• message the message the server responded with in the body

This is the most common thrown error, you should expect and handle it each time you use any of the library methods

Example: Getting a key throws an ApiResponseError if the key is invalid

If you try to GET an invalid key using apiKeys.getKey("invalid-key"), the server responds with a 404 error and an ApiResponseError is thrown

ApiResponseError: (404): Invalid client key

"404" is the statusCode, "Invalid client Key" is the message, you can access these properties using error.statusCode and error.message respectively

Error

Unknown error, just a normal javascript error

Handling Errors the Right Way

Since all the possible thrown errors are instances of classes, we can check the type of the thrown error and handle it accordingly

try {
  const key = await theAuthAPI.apiKeys.getKey('KEY');
} catch (error) {
  if (error instanceof ApiResponseError) {
    // handle response error
  }
  if (error instanceof ApiRequestError) {
    // handle network error
  }
  // unknown error
  throw error;
}

Typescript

This library is written in Typescript, types are provided out of the box.

Example of usage with Typescript:

import TheAuthAPI from 'theauthapi';
import { Project } from 'theauthapi/dist/types';

const client = new TheAuthAPI('ACCESS_KEY');

async function getProjectsIds(accountId: string): Promise<string[]> {
  const projects: Project[] = await client.projects.getProjects(accountId);
  return projects.map((project) => project.name);
}

⚠️ Works in Node.js 16+ and all modern bundlers. Not supported in Node.js 10–14.

📙 Further Reading

• Create your account https://theauthapi.com
• View our Knowledge Base help centre
• Read our API docs
• Articles on best Auth practice - https://theauthapi.com/articles
• Meet the team behind The Auth API - That API Company