Authentication

When your workflows and agents interact with external APIs or user-specific data, they need a way to authenticate. There are two separate concerns: authenticating to the Culvii platform when you deploy, and giving steps the credentials they need to call external services.

Authenticating to the platform

The @culvii/kit SDK has no auth API — it only builds workflow and agent definitions. Authentication to the platform is handled entirely by the culvii CLI, not by your code.

Sign in once with the CLI, then deploy. The CLI manages your session and attaches the right credentials to each request.

# Sign in (opens a browser-based login)
culvii login

# Deploy the definitions discovered in your project
culvii deploy --env sandbox --workspace my-workspace

For non-interactive contexts like CI, create an API key with culvii key create and provide it to the CLI via your environment instead of an interactive login. Never embed platform tokens in your workflow or agent definitions — keep them in the CLI session or environment.

import { Workflow } from '@culvii/kit';

// Your code only builds the definition. The CLI deploys it.
export const workflow = new Workflow({
  id: 'my-workflow',
  name: 'My Workflow',
});

Using credentials in steps

When defining a step that interacts with external services, you can configure it to use credentials stored on the platform.

import { Step } from '@culvii/kit';

const fetchUserData = new Step({
  name: 'Fetch User Data',
  type: 'http',
  credentials: {
    name: 'My API Auth',
    id: 'credential-id-here'
  },
  params: {
    url: 'https://api.example.com/user',
    method: 'GET'
  }
});

Keep your tokens secure. Never hardcode them in your workflow definitions. Always pass them in at runtime from your secure backend or environment variables.