Applications & keys

custral api POST applications '{"name":"Billing Sync","type":"internal"}'

curl -X POST https://api.custral.com/v1/applications \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Billing Sync","type":"internal"}'

const app = await custral.applications.create({
  name: "Billing Sync",
  type: "internal",
});

{
  "id": "app_3Ab9xK2mQ7",
  "name": "Billing Sync",
  "description": "Mirrors invoices into Deals",
  "type": "internal",
  "status": "private",
  "rails": "internal",
  "url": "",
  "createdAt": "2026-07-23T18:04:11.000Z",
  "updatedAt": "2026-07-23T18:04:11.000Z"
}

custral api POST applications '{"name":"Billing Sync","type":"internal"}'

curl -X POST https://api.custral.com/v1/applications \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Billing Sync","type":"internal"}'

const app = await custral.applications.create({
  name: "Billing Sync",
  type: "internal",
});

{
  "id": "app_3Ab9xK2mQ7",
  "name": "Billing Sync",
  "description": "Mirrors invoices into Deals",
  "type": "internal",
  "status": "private",
  "rails": "internal",
  "url": "",
  "createdAt": "2026-07-23T18:04:11.000Z",
  "updatedAt": "2026-07-23T18:04:11.000Z"
}

An application is the container your integration lives in; its keys are what you authenticate with. Every other endpoint in this reference needs a key, so this is where an integration starts.

Two ways in

A key can’t be the entry point to itself. A key belongs to an application, and an application has to be created by someone already signed in. So these endpoints accept either credential:

a session, for bootstrapping before any key exists, custral login → pick an org → create an application → mint a key
an API key holding applications:manage, for managing applications programmatically afterwards

A key may not mint a key with scopes it does not itself hold. That request is refused with insufficient_scope. Escalating beyond your current key is a job for the dashboard or the CLI, which authenticate as a signed-in human.

You can also do all of this from Settings → Applications in the dashboard, or from an MCP client. See MCP. Key revocation is deliberately not exposed over MCP, since it is immediate and irreversible.

The Application object

{
  "id": "app_3Ab9xK2mQ7",
  "name": "Billing Sync",
  "description": "Mirrors invoices into Deals",
  "type": "internal",
  "status": "private",
  "rails": "internal",
  "url": "",
  "createdAt": "2026-07-23T18:04:11.000Z",
  "updatedAt": "2026-07-23T18:04:11.000Z"
}

Attributes

string

Unique identifier, prefixed app_.

string

Human-readable name, shown in Settings → Applications.

string

internal for something you run yourself, workflow for an app that plugs into workflows.

string

private, unlisted, or public, who can discover the application.

string

How the application is invoked, internal or webhook.

The API key object

Key metadata. The secret itself is returned exactly once, at creation, and is hashed at rest. Nothing can retrieve it afterwards. It is excluded from this shape and from the service that lists keys, so no endpoint can return it.

{
  "id": "key_5Bc0xJ1kP4",
  "applicationId": "app_3Ab9xK2mQ7",
  "name": "production",
  "type": "secret",
  "keyPreview": "sk_live_abc…",
  "scopes": ["records:read", "records:write", "objects:read"],
  "environment": "live",
  "status": "active",
  "expiresAt": null,
  "lastUsedAt": "2026-07-23T19:12:44.000Z",
  "createdAt": "2026-07-23T18:04:11.000Z"
}

Attributes

string

Unique identifier, prefixed key_. This is what you pass to revoke a key.

string

secret (sk_…) for server-side use, or publishable (pk_…) for the browser.

string

A non-sensitive prefix for identifying the key in a list. Not usable for auth.

string[]

What the key may do. An empty array means the key can only call /v1/me. It authenticates but authorises nothing.

string

live or test.

string

active, or inactive once revoked.

string | null

ISO 8601 expiry, or null for a key that doesn’t expire.

string | null

When the key last authenticated a request.

Create an application

string

required

A human-readable name. Shown in Settings → Applications.

string

required

internal for something you run yourself, workflow for an app that plugs into workflows.

string

default:"private"

private, unlisted, or public, who can discover the application.

custral api POST applications '{"name":"Billing Sync","type":"internal"}'

curl -X POST https://api.custral.com/v1/applications \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Billing Sync","type":"internal"}'

const app = await custral.applications.create({
  name: "Billing Sync",
  type: "internal",
});

{
  "id": "app_3Ab9xK2mQ7",
  "name": "Billing Sync",
  "type": "internal",
  "status": "private"
}

Mint a key

Always pass scopes. A key minted without them authenticates fine and is authorised for nothing. Every endpoint answers insufficient_scope and only /v1/me works. It looks like a working key right up until the first real call.

string

required

secret (sk_…) for server-side use, or publishable (pk_…) for the browser.

string[]

What the key may do. See Scopes.

string

default:"live"

live or test.

integer

Auto-expire the key after N days. Omit for a key that doesn’t expire.

The plaintext key comes back once. It’s hashed at rest, so nothing can show it to you again. Store it before you close the terminal; if you lose it, revoke it and mint another.

custral api POST applications/app_3Ab9xK2mQ7/keys \
  '{"type":"secret","name":"production","scopes":["records:read","records:write","objects:read"]}'

const {plaintextKey} = await custral.applications.createKey("app_3Ab9xK2mQ7", {
  type: "secret",
  name: "production",
  scopes: ["records:read", "records:write", "objects:read"],
});
// Shown once — store it now.

{
  "key": {
    "id": "key_5Bc0xJ1kP4",
    "keyPreview": "sk_live_abc…",
    "scopes": ["records:read", "records:write", "objects:read"],
    "environment": "live"
  },
  "plaintextKey": "sk_live_AbC…the-only-time-you-see-this"
}

Verify a key

GET /v1/me is the “does this key work, and what can it do?” probe. Any valid key may call it, no scope required. The fastest way to confirm a key you just minted carries the scopes you meant.

curl https://api.custral.com/v1/me \
  -H "Authorization: Bearer sk_live_..."

const me = await custral.me();

{
  "orgId": "org_3Ab9xK2mQ7",
  "organizationName": "Acme Inc",
  "applicationId": "app_3Ab9xK2mQ7",
  "keyId": "key_5Bc0xJ1kP4",
  "keyPreview": "sk_live_abc…",
  "environment": "live",
  "scopes": ["records:read", "records:write", "objects:read"]
}

Revoke a key

Revocation takes effect immediately, every integration holding the key breaks at once, and it cannot be restored. The response carries a success flag: true when the key was deactivated, and false when no key matched the id. A key that was already revoked, or never existed. A missing key is reported as success: false, not as an error.

custral api DELETE applications/app_3Ab9xK2mQ7/keys/key_5Bc0xJ1kP4

curl -X DELETE https://api.custral.com/v1/applications/app_3Ab9xK2mQ7/keys/key_5Bc0xJ1kP4 \
  -H "Authorization: Bearer sk_live_..."

const {success} = await custral.applications.revokeKey(
  "app_3Ab9xK2mQ7",
  "key_5Bc0xJ1kP4",
);

{
  "success": true
}

Scopes

Scope	Grants
`records:read`	Read records
`records:write`	Create + update records
`objects:read`	Read the object/property schema
`conversations:read`	Read conversations + dispositions
`conversations:write`	Update, create, and add messages to conversations
`tasks:read`	Read tasks
`applications:manage`	Create applications and mint keys
`webhooks:manage`	Register webhooks
`mcp:read`	Connect an MCP client
`mcp:write`	Let an MCP client take write actions

Grant the narrowest set that works. applications:manage is the one to be careful with. A key holding it can mint further keys.

Introduction

Endpoints

Embeds & real-time

Two ways in

The Application object

Attributes

The API key object

Attributes

Create an application

Mint a key

Verify a key

Revoke a key

Scopes

​Two ways in

​The Application object

​Attributes

​The API key object

​Attributes

​Create an application

​Mint a key

​Verify a key

​Revoke a key

​Scopes

Two ways in

The Application object

Attributes

The API key object

Attributes

Create an application

Mint a key

Verify a key

Revoke a key

Scopes