Auth #

Sign up for the cat API #

Go to the sign up page of the cat API and register your account. It allows you to have 10k requests per month with a free account. You will get an API key by email after the registration. We will use this API key for authentication later on.

The cat API docs #

You can find detailed documentation of the cat API here. You need to revisit this page while building the integration.

Add auth to the app #

Open the thecatapi/index.ts file and add the highlighted lines for authentication.

import defineApp from '../../helpers/define-app';
import auth from './auth';

export default defineApp({
  name: 'The cat API',
  key: 'thecatapi',
  iconUrl: '{BASE_URL}/apps/thecatapi/assets/favicon.svg',
  authDocUrl: 'https://automatisch.io/docs/apps/thecatapi/connection',
  supportsConnections: true,
  baseUrl: 'https://thecatapi.com',
  apiBaseUrl: 'https://api.thecatapi.com',
  primaryColor: '000000',
  auth,
});

Define auth fields #

Let's create the auth/index.ts file inside of the thecatapi folder.

mkdir auth
touch auth/index.ts

Then let's start with defining fields the auth inside of the auth/index.ts file as follows:

export default {
  fields: [
    {
      key: 'screenName',
      label: 'Screen Name',
      type: 'string' as const,
      required: true,
      readOnly: false,
      value: null,
      placeholder: null,
      description:
        'Screen name of your connection to be used on Automatisch UI.',
      clickToCopy: false,
    },
    {
      key: 'apiKey',
      label: 'API Key',
      type: 'string' as const,
      required: true,
      readOnly: false,
      value: null,
      placeholder: null,
      description: 'API key of the cat API service.',
      clickToCopy: false,
    },
  ],
};

We have defined two fields for the auth.

• The apiKey field will be used to authenticate the requests to the cat API.
• The screenName field will be used to identify the connection on the Automatisch UI.

Verify credentials #

So until now, we integrated auth folder with the app definition and defined the auth fields. Now we need to verify the credentials that the user entered. We will do that by defining the verifyCredentials method.

Start with adding the verifyCredentials method to the auth/index.ts file.

import verifyCredentials from './verify-credentials';

export default {
  fields: [
    // ...
  ],

  verifyCredentials,
};

Let's create the verify-credentials.ts file inside the auth folder.

import { IGlobalVariable } from '@automatisch/types';

const verifyCredentials = async ($: IGlobalVariable) => {
  // TODO: Implement verification of the credentials
};

export default verifyCredentials;

We generally use the users/me endpoint or any other endpoint that we can validate the API key or any other credentials that the user provides. For our example, we don't have a specific API endpoint to check whether the credentials are correct or not. So we will randomly pick one of the API endpoints, which will be the GET /v1/images/search endpoint. We will send a request to this endpoint with the API key. If the API key is correct, we will get a response from the API. If the API key is incorrect, we will get an error response from the API.

Let's implement the authentication logic that we mentioned above in the verify-credentials.ts file.

import { IGlobalVariable } from '@automatisch/types';

const verifyCredentials = async ($: IGlobalVariable) => {
  await $.http.get('/v1/images/search');

  await $.auth.set({
    screenName: $.auth.data.screenName,
  });
};

export default verifyCredentials;

Here we send a request to the /v1/images/search endpoint with the API key. If we get a response from the API, we will set the screen name to the auth data. If we get an error response from the API, it will throw an error.

Is still verified? #

We have implemented the verifyCredentials method. Now we need to check whether the credentials are still valid or not for the test connection functionality in Automatisch. We will do that by defining the isStillVerified method.

Start with adding the isStillVerified method to the auth/index.ts file.

import verifyCredentials from './verify-credentials';
import isStillVerified from './is-still-verified';

export default {
  fields: [
    // ...
  ],

  verifyCredentials,
  isStillVerified,
};

Let's create the is-still-verified.ts file inside the auth folder.

import { IGlobalVariable } from '@automatisch/types';
import verifyCredentials from './verify-credentials';

const isStillVerified = async ($: IGlobalVariable) => {
  await verifyCredentials($);
  return true;
};

export default isStillVerified;

We will use the verifyCredentials method to check whether the credentials are still valid or not. If the credentials are still valid, we will return true. Otherwise, it will throw an error which will automatically be handled by Automatisch.

Test the authentication #

Now we have completed the authentication of the cat API. Go to the My Apps page in Automatisch, try to add a new connection, select The Cat API and use the API Key you got with an email. Then you can also check the test connection and reconnect functionality there.

Let's move on to the next page to build a trigger.