Skip to main content

​
Overview

The CredentialDefinition type defines authentication credentials that can be used by tools in your plugin. Credentials can have custom authentication logic and support localization.

​
Type Definition

type CredentialDefinition = {
  name: string
  display_name: Record<string, string>
  description: Record<string, string>
  icon: string
  parameters: ParameterDefinition[]
  authenticate?: (args: {
    credential: Record<string, any>
    extra: Record<string, any>
  }) => Promise<any> | any
}

​
Properties

​
name
string
required
The unique identifier for the credential.Example: "api-key" or "oauth-token"
​
display_name
Record<string, string>
required
Localized display names for the credential.Example:
{
  en_US: "API Key",
  es_ES: "Clave API"
}
​
description
Record<string, string>
required
Localized descriptions explaining what the credential is used for.Example:
{
  en_US: "Your API key for authentication",
  es_ES: "Tu clave API para autenticación"
}
​
icon
string
required
An emoji or icon representing the credential.Example: "🔑" or "🔐"
​
parameters
ParameterDefinition[]
required
An array of parameter definitions that describe the fields required for this credential.Example:
[
  {
    name: "api_key",
    display_name: { en_US: "API Key" },
    description: { en_US: "Enter your API key" },
    type: "string",
    required: true
  }
]
​
authenticate
function
Optional authentication handler that validates or transforms the credential before use.Parameters:
  • args.credential - The credential values provided by the user
  • args.extra - Additional context or configuration data
Returns: Validated or transformed credential dataExample:
authenticate: async ({ credential, extra }) => {
  // Validate the API key
  const response = await fetch("https://api.example.com/validate", {
    headers: { "Authorization": `Bearer ${credential.api_key}` }
  })
  
  if (!response.ok) {
    throw new Error("Invalid API key")
  }
  
  return credential
}

​
Usage

Credentials are registered using the addCredential() method on the plugin instance: 
import { createPlugin } from "@choiceopen/atomemo-plugin-sdk-js"

const plugin = await createPlugin({
  name: "my-plugin",
  display_name: { en_US: "My Plugin" },
  description: { en_US: "A plugin with credentials" },
  icon: "🔌",
  locales: ["en_US"]
})

plugin.addCredential({
  name: "api-key",
  display_name: {
    en_US: "API Key"
  },
  description: {
    en_US: "Your API key for authentication"
  },
  icon: "🔑",
  parameters: [
    {
      name: "key",
      display_name: { en_US: "API Key" },
      description: { en_US: "Enter your API key" },
      type: "string",
      required: true
    }
  ],
  authenticate: async ({ credential }) => {
    // Validate the credential
    if (!credential.key || credential.key.length < 10) {
      throw new Error("Invalid API key format")
    }
    return credential
  }
})

​
Parameter Types

The parameters array contains parameter definitions from the @choiceopen/atomemo-plugin-schema package. Common parameter types include:
  • string - Text input
  • number - Numeric input
  • boolean - Checkbox/toggle
  • array - List of values
  • object - Structured data

​
Authentication Flow

  1. User provides credential values through the Atomemo interface
  2. If authenticate is defined, it’s called with the credential and extra data
  3. The authenticate function validates and optionally transforms the credential
  4. On success, the credential is stored and made available to tools
  5. On failure, an error is returned to the user

​
Example with OAuth

plugin.addCredential({
  name: "oauth-token",
  display_name: {
    en_US: "OAuth Token"
  },
  description: {
    en_US: "OAuth 2.0 authentication token"
  },
  icon: "🔐",
  parameters: [
    {
      name: "access_token",
      display_name: { en_US: "Access Token" },
      description: { en_US: "OAuth access token" },
      type: "string",
      required: true
    },
    {
      name: "refresh_token",
      display_name: { en_US: "Refresh Token" },
      description: { en_US: "OAuth refresh token" },
      type: "string",
      required: false
    }
  ],
  authenticate: async ({ credential, extra }) => {
    // Verify the token is valid
    const response = await fetch("https://oauth.example.com/verify", {
      headers: { "Authorization": `Bearer ${credential.access_token}` }
    })
    
    if (!response.ok) {
      throw new Error("Invalid or expired token")
    }
    
    return credential
  }
})

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us