Create Custom Credential

This guide shows how to add a custom credential type for a service your workflows or nodes need to call.

Use this guide when

Reach for a custom credential type when:

a node depends on a non-standard API key or token
users need structured public fields such as baseUrl, endpoint, or tenant IDs
you want a real test(...) step instead of checking environment variables manually

Example scenario

Imagine you are building a my-service.apiKey credential for a custom REST API.

The goal is:

define the credential schema
build a typed session from configured values
let nodes request the credential through a named slot

Step 1: define the credential type

import type { CredentialType } from "@codemation/core";

type MyServicePublicConfig = Readonly<{ baseUrl?: string }>;
type MyServiceMaterial = Readonly<{ apiKey?: string }>;
type MyServiceSession = Readonly<{ baseUrl: string; apiKey: string }>;

export const myServiceCredentialType = {
  definition: {
    typeId: "my-service.apiKey",
    displayName: "My Service API key",
    publicFields: [{ key: "baseUrl", label: "Base URL", type: "string", required: true }],
    secretFields: [{ key: "apiKey", label: "API key", type: "password", required: true }],
    supportedSourceKinds: ["db", "env", "code"] as const,
  },
  createSession: async (args) => ({
    baseUrl: String(args.publicConfig.baseUrl ?? ""),
    apiKey: String(args.material.apiKey ?? ""),
  }),
  test: async (args) => ({
    status:
      String(args.publicConfig.baseUrl ?? "").trim() !== "" && String(args.material.apiKey ?? "").trim() !== ""
        ? ("healthy" as const)
        : ("failing" as const),
    testedAt: new Date().toISOString(),
  }),
} satisfies CredentialType<MyServicePublicConfig, MyServiceMaterial, MyServiceSession>;

Step 2: register the credential type

register(app: CodemationAppContext) {
  app.registerCredentialType(myServiceCredentialType);
  app.discoverWorkflows("src/workflows");
}

Step 3: let a node request the credential

Your node config should declare a slot and accepted type IDs:

getCredentialRequirements(): ReadonlyArray<CredentialRequirement> {
  return [
    {
      slotKey: "myService",
      label: "My Service API key",
      acceptedTypes: ["my-service.apiKey"],
    },
  ];
}

Then the node implementation can resolve the typed session during execution:

const session = await ctx.getCredential<MyServiceSession>("myService");

Full example outcome

Once this is wired up, operators can bind a concrete credential instance to the myService slot and your node gets a typed runtime session instead of a loose secret string.

Create Custom Credential

On this page