Skip to content
Metronome Docs

Working with API keys

Create an API Key

Section titled “Create an API Key”

Once you have signed up and received your server names and master keys, you should create API keys for your other systems, granting them permissions appropriate to their function.

Metronome defines the following API key permissions:

  • api-key-write
  • api-key-read
  • policy-read
  • policy-write
  • item-read
  • telemetry-write
  • expiry-notice-read
  • expiry-notice-write

While find grained read and write permissions are offered, it’s expected that they will typically be granted together. The keys that you use to manage policies will likely have policy-read and policy-write. The keys that you use to manage other API keys will likely have api-key-read and api-key-write.

The following example assumes that the customer slug is the-flower-boutique which is hosted on the eu-west-1 cluster and that an approriate API key value has been put into the environment variable METRONOME_API_KEY. First one creates a client configuration that includes the server name and API key which will authenticate this call. One then calls the putApiKey method on the client, with the first parameter being the API key. Use the reserved word create to create a new API key. We must create an instance of the AccessManagementApi client to work with API keys.

sign-up.ts
import { AccessManagementApi, ServerConfiguration, createConfiguration, Permission } from "@privatedataservices/metronome-client";
import { explainError } from "./errors";


const clientConfig = createConfiguration( {
    baseServer: new ServerConfiguration("https://the-flower-boutique.dev.eu-west-1.privatedataservices.com", {}),
    authMethods: { ApiKeyAuth: process.env.METRONOME_API_KEY }
});
const amApiClient = new AccessManagementApi(clientConfig);


try {
    // Use the special API key ID of "create" for new keys.
    const response = await amApiClient.putApiKey("create", {description: "Data Protection Office policy management key", permissions: [Permission.policy_read, Permission.policy_write]});
    console.log("Created new API key successfully.  The ID for this key that should be used for authenticating Data Protection Office is %s.", response.apiKeyId);
} catch (err) {
    explainError(err);
}

Modify an API Key

Section titled “Modify an API Key”

To modify an API key, one configures the client and calls the putApiKey method much the same as the example which creates an API key. This time, one uses the API key which is to be modified as the first parameter to the putApiKey method call.

modify-api-key.ts
import { AccessManagementApi, ServerConfiguration, createConfiguration, Permission } from "@privatedataservices/metronome-client";
import { explainError } from "./errors";


const clientConfig = createConfiguration( {
    baseServer: new ServerConfiguration("https://the-flower-boutique.dev.eu-west-1.privatedataservices.com", {}),
    authMethods: { ApiKeyAuth: process.env.METRONOME_API_KEY }
});
const amApiClient = new AccessManagementApi(clientConfig);


try {
    const response = await amApiClient.putApiKey("eZaOEFEYj-just-an-example-okymCvaqj08=", {permissions: [Permission.item_read, Permission.policy_read, Permission.policy_write]});
    console.log("API key modified successfully.  The fields modified were %s", response.fieldsModified.join(", "));
} catch (err) {
    explainError(err);
}

Reading API Keys

Section titled “Reading API Keys”

To read an API key, one calls the getApiKey method on the client.

read-api-key.ts
import { ApiException, ValidationError, ValidationProblem, AccessManagementApi, ServerConfiguration, createConfiguration, Permission } from "@privatedataservices/metronome-client";
import { explainError } from "./errors";


const clientConfig = createConfiguration( {
    baseServer: new ServerConfiguration("https://the-flower-boutique.dev.eu-west-1.privatedataservices.com", {}),
    authMethods: { ApiKeyAuth: process.env.METRONOME_API_KEY }
});
const amApiClient = new AccessManagementApi(clientConfig);


try {
    const response = await amApiClient.getApiKey("eZaOEFEYj-just-an-example-okymCvaqj08=");
    console.log("API key details are ID: %s, description: %s, create date: %s, permissions: %s", response.apiKeyId, response.description, response.createDate, JSON.stringify(response.permissions));
} catch (err) {
    explainError(err);
}

Listing API Keys

Section titled “Listing API Keys”

The API key listing interface is pagenated. In the event that there are more than 1000 entries, the first call will receive 1000 items and a continuation token for your next call. The next call should specify the continuation token as the first parameter to the getManyApiKeys method. The second parameter is a key prefix, should you only wish to search for keys starting with a specific prefix. The third possible parameter specifies whether you wish to see the details of each key (includeData) or whether you wish only to receive a list of the keys themselves.

The method signature for this method is getManyApiKeys(nextContinuationToken, prefix, includeData). All parameters are optional.

list-api-key.ts
import { AccessManagementApi, ServerConfiguration, createConfiguration, ApiKeyData, ApiKeyListResponse, ApiKeyDataListResponse } from "@privatedataservices/metronome-client";
import { explainError } from "./errors";


const clientConfig = createConfiguration( {
    baseServer: new ServerConfiguration("https://the-flower-boutique.dev.eu-west-1.privatedataservices.com", {}),
    authMethods: { ApiKeyAuth: process.env.METRONOME_API_KEY }
});
const amApiClient = new AccessManagementApi(clientConfig);


const listApiKeyIDsExample = async () => {
    try {
        const response = await amApiClient.getManyApiKeys() as ApiKeyListResponse;
        console.log("Known API keys are: %s", JSON.stringify(response.result));
    } catch (err) {
        explainError(err);
    }
}


const listApiKeyDataExample = async () => {
    try {
        const response = await amApiClient.getManyApiKeys(undefined, undefined, true) as ApiKeyDataListResponse;


        response.result.forEach( (apiKey: ApiKeyData, index: number) => {
            console.log("API key %s has ID: %s, description: %s, create date: %s, permissions: %s", index, apiKey.apiKeyId, apiKey.description, apiKey.createDate, apiKey.permissions.join(", "));
        });
    } catch (err) {
        explainError(err);
    }
}