#FAQ & Troubleshooting

#Authentication

How do I authenticate? HTTP Basic with a Personal Access Token: Authorization: Basic base64(client_id:client_secret). The token scopes the request to your tenant.

I get 401 unauthorized. Check the base64 encoding is client_id:client_secret (colon-separated) and that the token hasn't been revoked. See Auth & API Gateway.

I get 403 forbidden even though I'm authenticated. You're authenticated but not authorized for that resource/action. You need a grant (intra-tenant) or, for cross-tenant data, both a share and a grant. See Shares & Grants.

#Errors & responses

What shape are errors? Always { "error": { "status", "code", "message", "details" } }. Rely on the HTTP status code; status just mirrors it. See Auth & API Gateway.

What does 422 mean? A validation error — usually the request body didn't match the schema (entity attributes not matching the entity type's JSON schema, or a malformed filter). The details object pinpoints the field.

What does 409 conflict mean? A duplicate identifier key (an upsert/insert collided on the identifier attributes) or a cardinality violation on a relationship.

#Querying

Offset or keyset pagination? Use page/limit for simple offset paging, or cursor (from a prior response's next_cursor) for stable keyset iteration over large sets. They are mutually exclusive — send one or the other, never both.

My filter on an attribute returns nothing / errors. Filtering and sorting only work on attributes the entity type marks as indexed. Add the attribute to the type's indexed configuration. See Entities & Data Model.

REST query vs GraphQL — which should I use? They read the same data. Use GraphQL for a typed graph view with nested edges/node; use the REST query for composite filters, counts, and keyset pagination. See Querying & GraphQL.

How do I turn a GraphQL query into a workflow step? Use the interactive converter at /graphql/ — it emits a QueryEntity action config you can paste into a workflow.

#Workflows & jobs

Inline action or referenced job? Inline for small, step-local logic; a referenced job when the logic is reused across workflows. See Workflows.

My workflow doesn't run. Confirm it's activated for your tenant and has a trigger (event/cron/webhook). An unactivated definition never runs. See Triggers.

How do I pass data between steps? Smart values — e.g. {{ outputs.<stepId> }}, $jsonata, $literal, $if. See Smart Values.

#Bridge apps

My app spec activated but renders nothing for a user. Check the user's policy and the spec's principal config — widgets can be gated by grants. See Bridge Apps.

Heavy widgets render blank in the docs catalogue. Some widgets need build-time data; the catalogue supplies authored sample data for those. See Widget Catalogue.

#Secrets

How do I use a credential without hardcoding it? Store it as a tenant secret and reference it by name; the engine fetches the value at run time. See Secrets.

#Still stuck?

Browse the full API reference for exact request/response schemas, or read the relevant per-surface guide from the sidebar.