API & SDK · Get Started

Authorization

Authenticate BotDojo API requests and choose the right key scope.

2 min read

BotDojo authenticates API requests with an API key in the Authorization header. The key determines which Flow or Project resources the caller can use.

Request headers

Send these headers with JSON requests:

Authorization: YOUR_API_KEY
Content-Type: application/json

The header value is the API key itself. Do not add a Bearer prefix unless a specific integration instructs you to do so.

File uploads use the same Authorization header and a multipart content type. Your HTTP client normally generates the multipart boundary automatically.

Key scopes

Flow API key

A Flow API key can run one specific Flow. Prefer this key for a deployed application, webhook handler, or service that does not need access to other project resources.

To create one:

Open the Flow.
Select Settings → API.
Select Generate API Key.
Copy the key when it is shown.

Flow API settings showing key generation

Project API key

A Project API key can access API resources across one Project. Use it only in a trusted backend or administration process that requires that broader scope.

To create one:

Open Project Settings.
Select API Keys.
Select Generate Project API Key.
Name the key for the calling service and copy it when it is shown.

Account and Project IDs

Most API paths include account_id and project_id:

/v1/accounts/{account_id}/projects/{project_id}/...

Open Project Settings → Information to view and copy both identifiers.

Store keys safely

Keep keys on a server. Do not embed them in browser or mobile application bundles.
Store keys in a secret manager or protected environment variable.
Use separate keys for separate applications and environments.
Use a Flow API key when project-wide access is unnecessary.
Replace a key if it is exposed, shared accidentally, or no longer has a known owner.

Authorization errors

Status	Meaning	What to check
`401 Unauthorized`	The request has no valid API key.	Confirm the `Authorization` header and key value.
`403 Forbidden`	The key is valid but cannot access the resource.	Confirm the key scope and the Account, Project, and Flow IDs in the path.
`404 Not Found`	The resource is unavailable at that path.	Confirm the IDs and that the resource belongs to the Project.

Continue with the Quick Start or review the complete Flow Request contract.