Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/tailor-platform/sdk/llms.txt

Use this file to discover all available pages before exploring further.

Auth is a service for configuring authentication and authorization in your Tailor Platform application, providing user profile mapping, machine users, and OAuth 2.0 client configuration.

​
Overview

Auth provides:
  • User profile mapping to TailorDB types
  • Machine users for service-to-service authentication
  • OAuth 2.0 client configuration
  • Identity provider integration
For the official Tailor Platform documentation, see Auth Guide.

​
Configuration

Configure Auth service using defineAuth():
Definition Rules:
  • One auth per application: Each application can have exactly one Auth service
  • Configuration location: Define in tailor.config.ts using defineAuth() and reference directly in the config’s auth field
example/tailor.config.ts
import { defineAuth, defineConfig, defineIdp } from "@tailor-platform/sdk";
import { user } from "./tailordb/user";

const idp = defineIdp("my-idp", {
  authorization: "loggedIn",
  clients: ["default-idp-client"],
});

export const auth = defineAuth("my-auth", {
  userProfile: {
    type: user,
    usernameField: "email",
    attributes: {
      role: true,
    },
  },
  machineUsers: {
    "manager-machine-user": {
      attributes: {
        role: "MANAGER",
      },
    },
  },
  oauth2Clients: {
    sample: {
      redirectURIs: ["https://example.com/callback"],
      description: "Sample OAuth2 client",
      grantTypes: ["authorization_code", "refresh_token"],
    },
  },
  idProvider: idp.provider("sample", "default-idp-client"),
});

export default defineConfig({
  auth,
});

​
User Profile

Maps authenticated identities to a TailorDB type: 
userProfile: {
  type: user,              // TailorDB type for user records
  usernameField: "email",  // Field used as username (must be unique)
  attributes: {
    role: true,            // Enable 'role' as a user attribute
  },
},
Example TailorDB type for user profile:
example/tailordb/user.ts
import { db } from "@tailor-platform/sdk";

export const user = db.type("User", {
  email: db.string().unique(), // usernameField must have unique constraint
  role: db.enum(["MANAGER", "STAFF"]),
  ...db.fields.timestamps(),
});
export type user = typeof user;
​
type
TailorDBType
required
The TailorDB type that stores user records
​
usernameField
string
required
The field in the TailorDB type used as the username. This field must have a unique constraint (.unique()) since it is used to uniquely identify users.
​
attributes
object
required
Specifies which fields from the TailorDB type are used as user attributes. Set to true to enable a field. Enabled attributes must be assigned values in all machine user definitions. Only fields with ValueOperand types (string, boolean, string[], boolean[]) can be used as attributes.

​
Attribute List

In addition to attributes (key-value map), you can configure attributeList to expose UUID-type fields as an ordered list: 
userProfile: {
  type: user,
  usernameField: "email",
  attributes: { role: true },
  attributeList: ["organizationId", "teamId"],
},
​
attributeList
string[]
An array of field names from the TailorDB type. These fields will be exposed as an ordered list of UUIDs. Only UUID-type fields (non-array) can be included in the attribute list.
The attributeList values are accessible via user.attributeList as a tuple: 
// In a resolver
body: (context) => {
  const [organizationId, teamId] = context.user.attributeList;
},

// In TailorDB hooks
.hooks({
  field: {
    create: ({ user }) => user.attributeList[0], // First UUID from list
  },
})

​
Machine User Attributes (without userProfile)

When you want to use machine users without defining a userProfile, define machineUserAttributes instead: 
import { defineAuth, t } from "@tailor-platform/sdk";

export const auth = defineAuth("my-auth", {
  machineUserAttributes: {
    role: t.string(),
    isActive: t.bool(),
    tags: t.string({ array: true }),
  },
  machineUsers: {
    "admin-machine-user": {
      attributes: { role: "ADMIN", isActive: true, tags: ["root"] },
    },
  },
});
To update types in user-defined.d.ts, run: 
tailor-sdk generate

​
Machine Users

Service accounts for automated access without user interaction: 
machineUsers: {
  "admin-machine-user": {
    attributes: { role: "ADMIN" },
  },
  "readonly-machine-user": {
    attributes: { role: "READER" },
  },
},
​
attributes
object
required
Values for attributes enabled in userProfile.attributes (or all fields defined in machineUserAttributes when userProfile is omitted). All enabled fields must be set here. These values are accessible via user.attributes.
​
attributeList
string[]
Values for fields enabled in userProfile.attributeList. Must be an array of valid UUIDs in the same order as declared in userProfile.
Machine users are useful for:
  • CI/CD pipelines
  • Background jobs
  • Service-to-service communication
  • E2E testing
Get a machine user token using the CLI: 
tailor-sdk machineuser token <name>

​
Using auth.invoker()

The auth.invoker() method creates a type-safe reference to a machine user for use in workflow triggers:
example/resolvers/triggerWorkflow.ts
import { createResolver, t } from "@tailor-platform/sdk";
import { auth } from "../tailor.config";
import orderProcessingWorkflow from "../workflows/order-processing";

export default createResolver({
  name: "triggerOrderProcessing",
  description: "Trigger the order processing workflow",
  operation: "mutation",
  input: {
    orderId: t.string().description("Order ID to process"),
    customerId: t.string().description("Customer ID for the order"),
  },
  body: async ({ input }) => {
    // Trigger workflow with machine user permissions
    const workflowRunId = await orderProcessingWorkflow.trigger(
      { orderId: input.orderId, customerId: input.customerId },
      { authInvoker: auth.invoker("manager-machine-user") },
    );
    return { workflowRunId };
  },
  output: t.object({
    workflowRunId: t.string(),
  }),
});
The invoker() method is type-safe and only accepts machine user names defined in the auth configuration.

​
OAuth 2.0 Clients

Configure OAuth 2.0 clients for third-party applications: 
oauth2Clients: {
  "my-oauth2-client": {
    redirectURIs: [
      "https://example.com/callback",
      `${website.url}/callback`,  // Type-safe URL from StaticWebsite
    ],
    description: "My OAuth2 client",
    grantTypes: ["authorization_code", "refresh_token"],
    accessTokenLifetimeSeconds: 3600,    // 1 hour
    refreshTokenLifetimeSeconds: 604800, // 7 days
    requireDpop: true,                   // Require DPoP for this client
  },
},
​
redirectURIs
string[]
required
Allowed redirect URIs after authentication
​
description
string
Optional description of the client
​
grantTypes
string[]
required
Supported OAuth 2.0 grant types:
  • authorization_code - Standard OAuth 2.0 authorization code flow
  • refresh_token - Allow refreshing access tokens
​
accessTokenLifetimeSeconds
number
Optional access token lifetime in seconds. Minimum: 60 seconds, Maximum: 86400 seconds (1 day). If not specified, uses platform default.
​
refreshTokenLifetimeSeconds
number
Optional refresh token lifetime in seconds. Minimum: 60 seconds, Maximum: 604800 seconds (7 days). If not specified, uses platform default.
​
requireDpop
boolean
Optional boolean to require DPoP (Demonstrating Proof of Possession) for this client. When set to true, the client must use DPoP tokens for authentication.
Get OAuth2 client credentials using the CLI: 
tailor-sdk oauth2client get <name>

​
Identity Provider

Connect to an external identity provider: 
idProvider: idp.provider("my-provider", "my-client"),
See IdP for configuring identity providers.

​
CLI Commands

Manage Auth resources using the CLI: 
# List machine users
tailor-sdk machineuser list

# Get machine user token
tailor-sdk machineuser token <name>

# List OAuth2 clients
tailor-sdk oauth2client list

# Get OAuth2 client credentials
tailor-sdk oauth2client get <name>

Build docs developers (and LLMs) love

Get started for freeTalk to us