API Keys

These endpoints let a poweruser credential — including the delegated temporary credential a hosted Custom App holds — create and manage client API keys: the scoped keys that call the client-side execution API (/clients/…). They mirror the Builder's API Management page one-for-one, which means an app can provision the key its triggers and scheduled scripts run under on first launch, rotate it, and revoke it, without a person ever seeing the secret.

Only client keys are managed here. Poweruser keys (pwrusr:…) are created, rotated and revoked from the Builder only; a delegated credential can never mint a full-scope poweruser key. Every request is capped to the caller by the same rules as the Builder: system keys are never creatable, and poweruser-linkage / end-user scoping may only name the caller unless the caller holds the Admin role.

Base URL

https://api.autessa.com/autessa_poweruser/keys

All endpoints are POST with a JSON body. Authenticate with a poweruser key or temporary credential in the Authorization header (no Bearer prefix):

Authorization: pwrusr:{id}:{secret}

Hosted apps must be granted the endpoints they use in the app's hostingPermissions → allowedPoweruserEndpoints (KEYS_CREATE, KEYS_GET, KEYS_ALL, KEYS_UPDATE, KEYS_DELETE, KEYS_ENABLE, KEYS_DISABLE, KEYS_REFRESH, KEYS_PERMISSIONS_ADD_GROUP, KEYS_PERMISSIONS_ADD_RESOURCE, KEYS_PERMISSIONS_DELETE_SPECIFIC, KEYS_PERMISSIONS_SET_ALL_FOR_TYPE, KEYS_PERMISSIONS_REMOVE_ALL_FOR_TYPE, KEYS_TRANSACTIONS_MONTHLY_STATS).

The API key object

Name
id
Type
string
Description
Opaque id of the key — the prefix before the : in the secret value.
Name
keyName
Type
string
Description
Display name shown in the key list.
Name
keyDescription
Type
string
Description
What the key is used for.
Name
allResources
Type
boolean
Description
When true the key may access every resource in the company and permissions is ignored.
Name
permissions
Type
array<object>
Description
Per-resource-type grants: { resourceType: "TOOL" | "AGENT" | "MANAGER" | "AUTESSADB" | "CUSTOM_WEBHOOK" | "ESIGNATURE_ENVELOPE", resourceIds: string[] }. An empty resourceIds acts as a wildcard for that type.
Name
isEnabled
Type
boolean
Description
A disabled key authenticates to nothing.
Name
rateLimitPerMinute
Type
integer
Description
Per-minute cap (default 60).
Name
rateLimitPerDay
Type
integer
Description
Per-day cap (default 5000; must be ≥ rateLimitPerMinute).
Name
allowedOrigins
Type
array<string>
Description
Optional CORS allowlist; empty means unrestricted.
Name
metadata.autessaDbMetadata
Type
object
Description
{ globalAllowedOperations: ["READ","WRITE","DELETE"], tablePermissions: { "<tableId>": ["READ","WRITE"] } } — per-table operation overrides win over the global set. An absent/empty list means all operations are allowed.

Scoped key for an app's background scripts
{
  "keyName": "support-internal-scripts",
  "keyDescription": "Used by the support desk's trigger and scheduled scripts.",
  "allResources": false,
  "isEnabled": true,
  "rateLimitPerMinute": 600,
  "rateLimitPerDay": 200000,
  "permissions": [
    { "resourceType": "AUTESSADB", "resourceIds": ["fQMiNu10sCdT", "6m3BMDOhub7D"] },
    { "resourceType": "TOOL", "resourceIds": ["DVb0iQNqSxOE"] }
  ],
  "metadata": {
    "autessaDbMetadata": {
      "globalAllowedOperations": ["READ"],
      "tablePermissions": { "fQMiNu10sCdT": ["READ", "WRITE"], "6m3BMDOhub7D": ["READ", "WRITE"] }
    }
  }
}

Create Key POST`/create`

Mints a new client key and returns its secret exactly once.

Request Body

Name
apiKey
Type
object
Description
The desired configuration — see The API key object. isSystemKey is ignored (always false).

Response

Name
keyValue
Type
string
Description
The full secret, formatted {keyId}:{secret}. Store it now; it is never returned again.
Name
apiKey
Type
object
Description
The stored configuration (without the secret).
Name
errors
Type
array<string>
Description
Array of error messages. Absent on success.

cURL
curl https://api.autessa.com/autessa_poweruser/keys/create \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": {"keyName": "support-internal-scripts", "allResources": false, "isEnabled": true}}'

JSON
{
  "keyValue": "c1f2a3b4-5d6e-4789-9abc-0def12345678:Xk9…",
  "apiKey": { "id": "c1f2a3b4-5d6e-4789-9abc-0def12345678", "keyName": "support-internal-scripts", "isEnabled": true }
}

Get Key POST`/get`

Fetches one key's configuration (never the secret). Keys outside your company report as not found.

Request Body

Name
apiKeyId
Type
string
Description
Id of the key.

Response

Name
apiKey
Type
object
Description
See The API key object.

cURL
curl https://api.autessa.com/autessa_poweruser/keys/get \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKeyId": "c1f2a3b4-5d6e-4789-9abc-0def12345678"}'

List Keys POST`/all`

Lists every client key in the company (secrets never included; the backend system key is omitted unless the caller is an Admin). Not paginated.

Response

Name
apiKeys
Type
array<object>
Description
The keys.

cURL
curl https://api.autessa.com/autessa_poweruser/keys/all \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Update Key POST`/update`

Replaces the stored configuration wholesale — start from the entity returned by /get. Does not rotate the secret and does not itself grant per-resource permissions.

Request Body

Name
apiKeyId
Type
string
Description
Id of the key.
Name
updatedApiKey
Type
object
Description
The complete desired configuration.

cURL
curl https://api.autessa.com/autessa_poweruser/keys/update \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKeyId": "c1f2…", "updatedApiKey": {"id": "c1f2…", "keyName": "support-internal-scripts", "rateLimitPerMinute": 120, "isEnabled": true}}'

Refresh Key POST`/refresh`

Rotates the secret. The previous secret stops working the moment this succeeds; the new value is returned once.

Request Body

Name
apiKeyId
Type
string
Description
Id of the key.

Response

Name
keyValue
Type
string
Description
The new secret, {keyId}:{secret}.

cURL
curl https://api.autessa.com/autessa_poweruser/keys/refresh \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKeyId": "c1f2a3b4-5d6e-4789-9abc-0def12345678"}'

Enable / Disable Key POST`/enable · /disable`

/disable makes the key authenticate to nothing immediately (it is not deleted). /enable re-activates it with its existing secret.

Request Body

Name
apiKeyId
Type
string
Description
Id of the key.

cURL
curl https://api.autessa.com/autessa_poweruser/keys/disable \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKeyId": "c1f2a3b4-5d6e-4789-9abc-0def12345678"}'

Delete Key POST`/delete`

Permanently deletes a key. The key must already be disabled.

Request Body

Name
apiKeyId
Type
string
Description
Id of the key.

Response

Name
deleted
Type
boolean
Description
Whether the key was deleted.

cURL
curl https://api.autessa.com/autessa_poweruser/keys/delete \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKeyId": "c1f2a3b4-5d6e-4789-9abc-0def12345678"}'

Permissions POST`/permissions/…`

Adjust a key's scoped grants. All are no-ops on a key with allResources = true.

Path	Body	Effect
`/permissions/add-resource`	`{ apiKeyId, resourceType, resourceId }`	Grant one resource.
`/permissions/add-group`	`{ apiKeyId, permissions: { resourceType, resourceIds } }`	Grant a set of resources of one type.
`/permissions/delete-specific`	`{ apiKeyId, resourceType, resourceId }`	Revoke one resource grant.
`/permissions/set-all-for-type`	`{ apiKeyId, resourceType }`	Replace per-id grants with a wildcard for the type.
`/permissions/remove-all-for-type`	`{ apiKeyId, resourceType }`	Revoke every grant of the type.

resourceType is one of TOOL, AGENT, MANAGER, AUTESSADB, CUSTOM_WEBHOOK, ESIGNATURE_ENVELOPE.

cURL
curl https://api.autessa.com/autessa_poweruser/keys/permissions/add-resource \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKeyId": "c1f2…", "resourceType": "AUTESSADB", "resourceId": "fQMiNu10sCdT"}'

Monthly Usage POST`/transactions/monthly-stats`

Aggregated request counts for a key in a given month, broken down by endpoint, agent, and tool.

Request Body

Name
apiKeyId
Type
string
Description
Id of the key.
Name
year
Type
integer
Description
Four-digit year.
Name
month
Type
integer
Description
Month (1–12).

cURL
curl https://api.autessa.com/autessa_poweruser/keys/transactions/monthly-stats \
  -H "Authorization: $POWERUSER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"apiKeyId": "c1f2…", "year": 2026, "month": 8}'

Base URL​

The API key object​

Create Key POST/create​

Request Body​

Response​

Get Key POST/get​

Request Body​

Response​

List Keys POST/all​

Response​

Update Key POST/update​

Request Body​

Refresh Key POST/refresh​

Request Body​

Response​

Enable / Disable Key POST/enable · /disable​

Request Body​

Delete Key POST/delete​

Request Body​

Response​

Permissions POST/permissions/…​

Monthly Usage POST/transactions/monthly-stats​

Request Body​

Base URL

The API key object

Create Key POST`/create`

Request Body

Response

Get Key POST`/get`

Request Body

Response

List Keys POST`/all`

Response

Update Key POST`/update`

Request Body

Refresh Key POST`/refresh`

Request Body

Response

Enable / Disable Key POST`/enable · /disable`

Request Body

Delete Key POST`/delete`

Request Body

Response

Permissions POST`/permissions/…`

Monthly Usage POST`/transactions/monthly-stats`

Request Body