🗝️

Adding API Key Authentication

API key authentication is a method to authenticate a client when sending a request to Graphweaver.

To add API Key authentication you must follow many steps:

  • Create a Data Entity to store the API Key data
  • Create a Data Provider for the above Data Entity
  • Provide the Data Provider to the Auth Plugin
  • Finally, pass the Auth Plugin to Graphweaver

Let’s look at each of these steps. First, we need to create a Data Entity to store the API Key: 

import { ArrayType, BigIntType, Entity, PrimaryKey, Property } from '@mikro-orm/core';
import { BaseEntity } from '@exogee/graphweaver-mikroorm';
import { ApiKeyStorage } from '@exogee/graphweaver-auth';

@Entity({ tableName: 'api_key' })
export class ApiKey extends BaseEntity implements ApiKeyStorage {
	@PrimaryKey({ type: BigIntType })
	id!: string;

	@Property({ type: String, fieldName: 'api_key' })
	key!: string;

	@Property({ type: String })
	secret!: string;

	@Property({ type: Boolean })
	revoked!: boolean;

	@Property({ type: ArrayType, default: [] })
	roles!: string[];
}

For the most part, the above Data Entity is like any other. The only real difference is that the class implements the ApiKeyStorage interface.

This means you must have an ID, Key and Secret property. Without these properties, the API Key authentication cannot work.

The secret is stored as a string here but the secret is never stored in plain text. Instead, we make sure to apply Argon2Id hashing to the secret before it is saved to the data provider.

Don’t forget to pass your data entity to your database connection as you normally would.

Once you have the Data Entity set you can create a data provider:

export const apiKeyDataProvider = new MikroBackendProvider(OrmApiKey, myConnection);

Here we are creating a MikroBackend provider which is connected to MySQL. But this could be any data provider storing the API Key data.

Once this is created we can pass the data provider to the auth plugin, here is an example: 

import Graphweaver from '@exogee/graphweaver-server';
import { AuthorizationContext, authApolloPlugin } from '@exogee/graphweaver-auth';

import { resolvers } from './schema';
// API Key Data Provider
import { apiKeyDataProvider } from './schema/auth';

export const graphweaver = new Graphweaver<AuthorizationContext>({
	resolvers,
	apolloServerOptions: {
		plugins: [authApolloPlugin(addUserToContext, apiKeyDataProvider)],
	},
});

As you can see above, we are providing the Apollo server with an authApolloPlugin. It is inside this plugin that we check for the API Key authentication.

We have also passed in the data provider apiKeyDataProvider we created in the previous step. This allows the plugin to fetch the API Key data when verifying the key and secret.

This is all you need to get API authentication working, yet you still need to know how to make a request.

To start you need to create an API Key via the Admin UI. Because the API Key needs a secret we’ll use the SecretFieldComponent from the @exogee/graphweaver-auth-ui-components package as a custom field. This component generates a secret value and api key when the button is clicked, though you can roll your own component to generate these. src/admin-ui/custom-fields/index.ts

customFields.set('ApiKey', [
	{
		name: 'secret',
		type: 'custom',
		component: SecretFieldComponent,
		hideOnTable: true,
		initialValue: '',
	},
]);

Ensure you’ve applied any roles required for this API key and create the entity.

Finally, now that the credentials are created you are ready to make an API request to Graphweaver.

To do that you must provide the API Key as a base64 encoded to the X-API-Key HTTP header in your request. Much the same as you would for a Basic Auth flow.

Here is an example curl request where the string of test:test ([key]:[secret])has been base64 encoded to dGVzdDp0ZXN0: 

curl --location 'http://localhost:9001/' \
--header 'x-api-key: dGVzdDp0ZXN0' \
--header 'Content-Type: application/json' \
--data '{"query":"query {\n    tasks {\n        id\n    }\n}","variables":{}}'

Exogee