Organization tRPC Procedures — Deployaar API Docs

Deployaar organizes all work inside organizations — every project, feature request, and billing plan belongs to an organization. The organization router handles creation, member management, and role assignment. The companion invitation router handles email-based invite flows. The userSettings router stores per-user AI provider preferences. All procedures require authentication.

Organization procedures

`organization.createOrg` — mutation

Creates a new organization. The authenticated user automatically becomes the owner and sole member of the new organization.

Input

name

string

required

Display name for the organization. Minimum 2 characters, maximum 100 characters.

slug

string

required

URL-safe identifier. Minimum 2 characters, maximum 100 characters. Pattern: ^[a-z0-9-]+$ — lowercase letters, numbers, and hyphens only.

logoUrl

string | null

Optional URL to a logo image. Must be a valid URL. Pass null or omit to leave blank.

Response

{
  "success": true,
  "message": "Organization created",
  "data": {
    "organization": {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "logoUrl": "https://cdn.acme.com/logo.png"
    }
  }
}

`organization.getMyOrgs` — query

Returns all organizations the authenticated user belongs to, along with the user’s role in each. No input required.

Response

{
  "success": true,
  "message": "Found",
  "data": {
    "organizations": [
      {
        "organization": {
          "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "name": "Acme Corp",
          "slug": "acme-corp",
          "logoUrl": null
        },
        "role": "owner"
      }
    ]
  }
}

`organization.getOrg` — query

Fetches a single organization by ID, including its current billing plan and status. The caller must be a member of the organization.

Input

organizationId

string (UUID)

required

The UUID of the organization to retrieve.

Response

{
  "success": true,
  "message": "Found",
  "data": {
    "organization": {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "logoUrl": null,
      "billingPlan": "pro",
      "billingStatus": "active"
    }
  }
}

`organization.getOrgMembers` — query

Returns all current members of an organization with their display names, email addresses, and roles.

Input

organizationId

string (UUID)

required

The UUID of the organization whose member list should be returned.

Response

{
  "success": true,
  "message": "Found",
  "data": {
    "members": [
      {
        "userId": "auth0|abc123",
        "organizationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "role": "owner",
        "userName": "Alice Johnson",
        "userEmail": "alice@acme.com",
        "userImage": "https://cdn.acme.com/avatars/alice.jpg"
      },
      {
        "userId": "auth0|def456",
        "organizationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "role": "member",
        "userName": "Bob Smith",
        "userEmail": "bob@acme.com",
        "userImage": null
      }
    ]
  }
}

`organization.inviteMember` — mutation

Directly adds an existing Deployaar user to the organization by their user ID. The caller must be an owner or admin. To invite someone who does not yet have a Deployaar account, use invitation.send instead.

Role hierarchy

Role	Capabilities
`owner`	Full access: billing, member management, all project operations
`admin`	Billing, member management, all project operations (cannot remove owners)
`member`	Project read/write, cannot manage billing or members

Input

organizationId

string (UUID)

required

The UUID of the organization to add the user to.

targetUserId

string

required

The Deployaar user ID of the person to invite.

role

string (enum)

required

The role to assign. One of: owner | admin | member.

Response

{
  "success": true,
  "message": "Member invited",
  "data": {
    "member": {
      "userId": "auth0|xyz789",
      "organizationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "role": "member"
    }
  }
}

`organization.removeMember` — mutation

Removes a user from the organization. The caller must be an owner or admin and cannot remove themselves.

Input

organizationId

string (UUID)

required

The UUID of the organization.

targetUserId

string

required

The user ID of the member to remove.

Response

{
  "success": true,
  "message": "Member removed",
  "data": {}
}

`organization.updateMemberRole` — mutation

Changes an existing member’s role. The caller must be an owner or admin.

Input

organizationId

string (UUID)

required

The UUID of the organization.

targetUserId

string

required

The user ID of the member whose role should be changed.

newRole

string (enum)

required

The role to assign. One of: owner | admin | member.

Response

{
  "success": true,
  "message": "Role updated",
  "data": {
    "member": {
      "userId": "auth0|def456",
      "organizationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "role": "admin"
    }
  }
}

Invitation procedures

The invitation router handles email-based invitations for users who may not yet have a Deployaar account.

`invitation.send` — mutation

Sends an email invitation to join an organization. The invite contains a signed token that the recipient uses to accept. Tokens expire after a fixed period. Caller must be an owner or admin.

Input

organizationId

string (UUID)

required

The UUID of the organization the recipient is being invited to.

string (email)

required

The recipient’s email address.

role

string (enum)

required

The role to assign on acceptance. One of: owner | admin | member.

Response

{
  "success": true,
  "message": "Invitation sent",
  "data": {
    "invitationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "email": "carol@acme.com",
    "role": "member"
  }
}

`invitation.getMyInvitations` — query

Returns all pending invitations addressed to the authenticated user’s email. No input required.

Response

{
  "success": true,
  "message": "Found",
  "data": {
    "invitations": [
      {
        "invitationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "organizationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "organizationName": "Acme Corp",
        "organizationSlug": "acme-corp",
        "inviterName": "Alice Johnson",
        "role": "member",
        "token": "tok_abcdef123456",
        "createdAt": "2024-01-20T09:00:00.000Z"
      }
    ]
  }
}

`invitation.getOrgInvitations` — query

Lists all pending invitations sent from a given organization. Caller must be an owner or admin of that organization.

Input

organizationId

string (UUID)

required

The UUID of the organization whose pending invitations should be listed.

Response

{
  "success": true,
  "message": "Found",
  "data": {
    "invitations": [
      {
        "invitationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "email": "carol@acme.com",
        "inviterName": "Alice Johnson",
        "role": "member",
        "token": "tok_abcdef123456",
        "createdAt": "2024-01-20T09:00:00.000Z",
        "expiresAt": "2024-01-27T09:00:00.000Z"
      }
    ]
  }
}

`invitation.accept` — mutation

Accepts a pending invitation using the signed token from the invitation email. The authenticated user is added to the organization with the role specified when the invitation was sent.

Input

token

string

required

The signed invitation token from the invitation email.

Response

{
  "success": true,
  "message": "Invitation accepted",
  "data": {
    "organizationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "role": "member"
  }
}

`invitation.decline` — mutation

Declines a pending invitation. The invitation is marked as declined and cannot be reused.

Input

token

string

required

The signed invitation token from the invitation email.

Response

{
  "success": true,
  "message": "Invitation declined",
  "data": {}
}

`invitation.revoke` — mutation

Revokes a pending invitation before it has been accepted. Caller must be an owner or admin of the organization.

Input

organizationId

string (UUID)

required

The UUID of the organization that sent the invitation.

invitationId

string (UUID)

required

The UUID of the invitation to revoke.

Response

{
  "success": true,
  "message": "Invitation revoked",
  "data": {}
}

User settings procedures

The userSettings router stores per-user AI provider and model preferences that override the organization defaults when the user’s plan permits.

`userSettings.getSettings` — query

Returns the AI provider configuration for the authenticated user. No input required.

Response

{
  "success": true,
  "message": "Found",
  "data": {
    "settings": {
      "userId": "auth0|abc123",
      "preferredProvider": "openai",
      "preferredModel": "gpt-4o",
      "hasApiKey": true,
      "createdAt": "2024-01-10T09:00:00.000Z",
      "updatedAt": "2024-01-18T14:30:00.000Z"
    }
  }
}

settings is null if the user has never saved preferences. hasApiKey is true when a personal API key is stored — the key itself is never returned in responses.

`userSettings.updateSettings` — mutation

Updates the user’s AI provider preferences and optionally stores a personal API key. The user’s plan must allow the selected provider; attempting to select a provider outside the plan ceiling throws 403 Forbidden.

Input

preferredProvider

string (enum) | null

One of: anthropic | openai | google | deepseek. Pass null to clear.

preferredModel

string | null

The preferred model identifier, e.g. "gpt-4o" or "claude-3-5-sonnet-20241022". Maximum 100 characters. Pass null to clear.

apiKey

string | null

A personal API key for the selected provider. Stored encrypted. Pass null to remove the stored key.

Response

{
  "success": true,
  "message": "Updated",
  "data": {
    "settings": {
      "userId": "auth0|abc123",
      "preferredProvider": "openai",
      "preferredModel": "gpt-4o",
      "hasApiKey": true,
      "createdAt": "2024-01-10T09:00:00.000Z",
      "updatedAt": "2024-01-19T10:00:00.000Z"
    }
  }
}

TypeScript example

import { trpc } from "~/trpc/client";

// Create an organization
const createOrgMutation = trpc.organization.createOrg.useMutation();

const { data: orgData } = await createOrgMutation.mutateAsync({
  name: "Acme Corp",
  slug: "acme-corp",
  logoUrl: null,
});

const organizationId = orgData.organization.id;

// List all orgs the current user belongs to
const { data: myOrgs } = trpc.organization.getMyOrgs.useQuery();

// List members of an organization
const { data: membersData } = trpc.organization.getOrgMembers.useQuery({ organizationId });

// Send an email invitation
const sendInviteMutation = trpc.invitation.send.useMutation();

await sendInviteMutation.mutateAsync({
  organizationId,
  email: "carol@acme.com",
  role: "member",
});

// Accept an invitation (called in the invite-accept flow)
const acceptMutation = trpc.invitation.accept.useMutation();

await acceptMutation.mutateAsync({ token: "tok_abcdef123456" });

// Update user AI settings
const updateSettingsMutation = trpc.userSettings.updateSettings.useMutation();

await updateSettingsMutation.mutateAsync({
  preferredProvider: "openai",
  preferredModel: "gpt-4o",
  apiKey: "sk-...",
});

REST equivalent (curl)

# Create an organization
curl -X POST https://api.deployaar.com/api/organizations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "slug": "acme-corp"}'

# List current user's organizations
curl https://api.deployaar.com/api/organizations \
  -H "Authorization: Bearer <token>"

# Get a specific organization
curl https://api.deployaar.com/api/organizations/{organizationId} \
  -H "Authorization: Bearer <token>"

# List members
curl https://api.deployaar.com/api/organizations/{organizationId}/members \
  -H "Authorization: Bearer <token>"

# Send an email invitation
curl -X POST https://api.deployaar.com/api/invitations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"organizationId": "...", "email": "carol@acme.com", "role": "member"}'

# Accept an invitation
curl -X POST https://api.deployaar.com/api/invitations/accept \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"token": "tok_abcdef123456"}'

# Update user settings
curl -X PATCH https://api.deployaar.com/api/user-settings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"preferredProvider": "openai", "preferredModel": "gpt-4o", "apiKey": "sk-..."}'

Overview

tRPC Routes

Webhooks

Documentation Index

​Organization procedures

​organization.createOrg — mutation

​Input

​Response

​organization.getMyOrgs — query

​Response

​organization.getOrg — query

​Input

​Response

​organization.getOrgMembers — query

​Input

​Response

​organization.inviteMember — mutation

​Role hierarchy

​Input

​Response

​organization.removeMember — mutation

​Input

​Response

​organization.updateMemberRole — mutation

​Input

​Response

​Invitation procedures

​invitation.send — mutation

​Input

​Response

​invitation.getMyInvitations — query

​Response

​invitation.getOrgInvitations — query

​Input

​Response

​invitation.accept — mutation

​Input

​Response

​invitation.decline — mutation

​Input

​Response

​invitation.revoke — mutation

​Input

​Response

​User settings procedures

​userSettings.getSettings — query

​Response

​userSettings.updateSettings — mutation

​Input

​Response

​TypeScript example

​REST equivalent (curl)

Build docs developers (and LLMs) love

Organization procedures

`organization.createOrg` — mutation

Input

Response

`organization.getMyOrgs` — query

Response

`organization.getOrg` — query

Input

Response

`organization.getOrgMembers` — query

Input

Response

`organization.inviteMember` — mutation

Role hierarchy

Input

Response

`organization.removeMember` — mutation

Input

Response

`organization.updateMemberRole` — mutation

Input

Response

Invitation procedures

`invitation.send` — mutation

Input

Response

`invitation.getMyInvitations` — query

Response

`invitation.getOrgInvitations` — query

Input

Response

`invitation.accept` — mutation

Input

Response

`invitation.decline` — mutation

Input

Response

`invitation.revoke` — mutation

Input

Response

User settings procedures

`userSettings.getSettings` — query

Response

`userSettings.updateSettings` — mutation

Input

Response

TypeScript example

REST equivalent (curl)