Skip to main content

Authentication and permissions

A project API key answers two questions: which project can this request access, and what can it do there? It does not sign in a person or inherit a team member's role.

Create keys in API keys in your project's navigation. For the dashboard steps, secret rotation, and module setup, see API keys. For a first request, follow the Quickstart.

Send the credential​

Send the complete token in the HTTP Authorization header:

Authorization: proj.KEY_ID.SECRET

Do not add a Bearer prefix, pass only the secret segment, or put the key in a URL.

Use the project ID that the key belongs to and the API base URL for the same environment. A production key cannot authenticate a request to a different project or to the test environment.

Choose permissions​

Permissions, also called scopes, define an operation and its allowed resources. This reference uses names such as workflows.run to identify an operation; choose the corresponding permission in the dashboard rather than sending a scope in the request header.

ServiceOperationsResource selection
Workflowsworkflows.read to list readable workflows and retrieve run status; workflows.run to execute, including through MCP.Individual workflows or all workflows.
AI chatllm.complete to create chat completions.Selected tiers: small, medium, large, or all tiers.
Embeddingsembeddings.create.The service as a whole.
Rerankingrerank.create.The service as a whole.
Speechspeech.synthesize for text-to-speech; speech.transcribe for audio-to-text.Separate permission for each direction.
Librarylibrary.read to browse/download, library.write to upload, library.delete to remove files.The entire project Library, not individual files or directories.
Databasesdatabases.read, databases.write, databases.delete, databases.schema, databases.query, and databases.admin for reading, writing, deleting rows, changing structure, running SQL, and provisioning databases respectively.Individual databases or all databases; project-wide operations require an all-databases grant.

Grant only what the integration needs. For example:

  • To run one workflow synchronously, grant Run on that workflow.
  • To queue it and poll the result, grant Run and Read status on that workflow.
  • To browse Library files, grant Library → Browse.
  • To import a Library CSV into a database, grant databases.write on that database and library.read. Polling the import also requires databases.read.

The endpoint reference identifies its required permissions. For example, listing databases requires databases.read on all databases, even if the key can already read a particular database.

Grants are additive​

An All workflows or All databases permission covers resources added later as well as existing ones. Leaving an individual resource unchecked does not override that broad grant. Remove the all-resources permission before narrowing access.

Run and read permissions are separate: permission to execute a workflow does not automatically allow listing it or retrieving a queued run's status. Similarly, database write access does not automatically grant read access.

Workflow access includes its actions​

A key that calls a workflow does not need direct API permissions for each service that the workflow uses internally. Granting permission to run a workflow allows its configured actions to execute, so review what the workflow does before exposing it to an integration.

Treat powerful database permissions carefully​

databases.query allows arbitrary SQL, not only read-only queries. databases.schema can remove tables or columns, and databases.admin can create or delete databases. Do not grant these merely to let an application read or update rows.

Keep credentials in trusted code​

Keep keys in server-side environment variables or a secret manager. Do not commit them, include them in browser bundles, or write them to logs. Your application's backend must check its users' access before using a project key on their behalf.

Use separate keys for integrations with different responsibilities. Permission changes apply to subsequent requests without replacing the secret. Disabling, rotating, or deleting a key can revoke access; removing a collaborator does not revoke project keys they may know. Review affected credentials when team access changes.

Some older keys may have full access. Review them and replace broad access with explicit permissions.

Code running on Intellectible​

A configured module receives its project key and API connection details through environment variables. Its key still needs the relevant permissions; a newly created module key starts without service permissions. See Using project services.

Workflow code nodes receive a short-lived, project-bound execution credential in INTELLECTIBLE_PROJECT_API_KEY. Send it in the same header, using the supplied INTELLECTIBLE_PROJECT_ID and INTELLECTIBLE_PUBLIC_API_URL. It has access to the running workflow's project; do not copy it out or treat it as a reusable integration key.

Other authentication methods​

Webhook deliveries use the webhook's configured verification rather than a project key. MCP requests use a project key with workflows.run permission on the target workflow.

Diagnose access failures​

  • 401 Unauthorized: the credential is missing, malformed, invalid, disabled, or belongs to another project/environment. Check the full token and header format.
  • 403 Forbidden: authentication may have succeeded, but the required permission or resource grant is missing. Some operations also use this status for resource-quota restrictions; read the response.
  • An empty workflow list: a valid key only sees workflows it can read. No read grants can produce an empty list rather than a permission error.

Do not repeatedly retry unchanged credentials or permissions. Correct the setup first, then make a small read-only request. See Errors, limits and retries.