API keys
API keys let code use the services in an Intellectible project: run workflows, access files and databases, or use AI services. Use them in an application's backend, a module, or an external integration that needs to work with your project.
Each key belongs to one project and has its own permissions, also called scopes. A key identifies the project and the operations a caller may perform; it does not sign in a person or inherit their team role. Anyone holding the secret can use those permissions, so treat it like a password.
Open API keys in your project's navigation to create and manage keys. Use a separate, clearly named key for each integration so you can change or revoke one without affecting the others.
Create a key
- Click Create API key.
- Give it a descriptive name, such as
Invoice service — production. - Expand the permission sections and select only the operations the integration needs. The creation form requires at least one permission.
- Decide whether to enable Make available to code running on Intellectible, explained below.
- Click Create, then copy the complete token into your secret store.
The token looks like proj.KEY_ID.SECRET. Copy the whole value, not just the final segment. It is shown when created and cannot be revealed again in the dashboard. If you lose it, rotate the secret or create a replacement key.
Choose permissions
Permissions describe both what a key can do and, where supported, which resources it can use.
| Area | Available access |
|---|---|
| Workflows | Run workflows, including through MCP, and read workflow listings or run status. Grant access to individual workflows or all workflows. |
| Library | Browse/download, upload, or delete files. These permissions cover the project's Library, not individual files or directories. |
| Databases | Read, write, delete rows, change schema, run SQL, or provision databases. Grant access per database or across all databases. |
| AI models | Create chat completions using selected model tiers or all tiers. |
| Embeddings and reranking | Create embeddings or rerank results, with separate permissions for each service. |
| Speech | Synthesise speech or transcribe audio, with separate permissions for each direction. |
For example, a service that starts one workflow and polls its result needs Run and Read status on that workflow. It does not need direct Library or database permissions simply because the workflow uses those services internally. Choose callable workflows carefully: permission to run one allows its configured actions to execute.
An All workflows or All databases grant also covers resources added later. Grants are additive: leaving a specific resource unchecked does not override an all-resources grant. Remove the broad grant if you want to restrict access to selected resources.
Run SQL permits arbitrary SQL, including destructive statements; it is not a read-only query permission. Schema can change or remove structure, and Provision can create or destroy databases. Grant these only when needed. See Databases.
Use a key in requests
Send the complete token in the HTTP Authorization header without a Bearer prefix:
Authorization: proj.KEY_ID.SECRET
For example, this read-only request lists files in the Library root. It requires Library → Browse (library.read). Set the environment variables securely before running it:
curl --request GET \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/library/files"
Use the API base URL for your environment and the project ID the key belongs to. The Public API reference describes endpoint paths, inputs, responses, and required permissions.
The Try the API section below the key list lets you explore endpoints and send requests from the dashboard. Enter your key, choose an endpoint, and review the inputs before selecting Send request. These are real requests against your project—not a simulation—so start with a read-only operation. The explorer keeps the entered key in the current tab rather than saving it for later.
Make a key available to module code
The Make available to code running on Intellectible option controls whether the platform retains the secret so it can supply it to your code:
- Off: only a hash is retained. You store the token yourself; Intellectible cannot recover it or automatically supply it to a module.
- On: an encrypted copy is retained for platform-managed use. The dashboard still does not reveal it again.
This choice is made at creation and cannot be changed later. It does not grant extra API permissions or automatically attach the key to every module.
A new module receives its own key with no service permissions initially. Grant the required permissions in API keys. In the module's Dev Machine → Overview → Project API key panel, Use key lets you select another eligible key.
Configured module code receives INTELLECTIBLE_PROJECT_API_KEY, INTELLECTIBLE_PROJECT_ID, and INTELLECTIBLE_PUBLIC_API_URL through its environment. Read these in server-side code rather than pasting secrets into source files or agent conversations. See Using project services for setup and restart requirements.
Change, disable, rotate, or delete a key
Select a key to edit its name and permissions, then click Save. Permission changes apply to subsequent API requests without issuing a new secret. You can remove all permissions from an existing key without deleting it.
Use the key's actions menu to Disable key, Enable key, or Delete key. Disabling temporarily rejects requests while preserving the configuration; deletion permanently revokes the key.
To replace a secret, open the key and choose Rotate secret. Rotation keeps its identity, name, and permissions, but invalidates the old secret immediately. It happens independently of the permission form's Save button. Copy the new token and update every external integration using it. Restart module development machines and redeploy running deployments that need to load the new credential.
For a planned replacement with less disruption, create a second narrowly scoped key, update and test the integration, then revoke the old one. If a secret has been exposed, disable or rotate it promptly rather than leaving it active during a migration.
Keep keys safe
Keep keys in server-side environment variables or a secret manager. Do not commit them to Git, include them in browser-delivered code, or paste them into logs, screenshots, or agent messages. Your application's backend should check what each user may do before using its project key on their behalf.
Project keys are service credentials, separate from team membership and application-user authentication. Removing a collaborator does not revoke project API keys they may know. Review and rotate or delete affected keys when access changes.
If a request fails, check the response:
- 401: check the complete token, project ID, enabled status, and header format. A rotated or deleted secret no longer works.
- 403: check the permission and resource target required by the endpoint. Also read the response for any project quota restriction.
- 429: a rate limit has been reached; reduce the request rate and retry with backoff.
Older keys may appear as having full access. Review these and replace broad access with the specific permissions each integration needs.