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.

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

npm install theauthapi
# or
yarn add theauthapi

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.

const TheAuthAPI = require('theauthapi');

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;
};

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")

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

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.

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)

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);
}

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
  }
}

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);
}

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.

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

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

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

Unknown error, just a normal javascript error

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;
}

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.

• 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