Skip to main content
A project is a named group of workflows inside one environment. It is the unit that access is granted on: you give a person a role on a project, and that role applies to every workflow the project owns. If your organization is small, you may only ever use the automatically-created Default Project. If you have several teams or customers, projects let you keep their workflows — and who can touch them — separate.

​
What a project is

FieldMeaning
idStable identifier, prefixed proj_.
nameHuman-readable name.
slugURL-safe name (^[a-z0-9]+(?:-[a-z0-9]+)*$).
descriptionOptional free text.
icon, colorDashboard presentation.
visibilityprivate. Projects are private to their grant holders.
A project lives in exactly one environment. The same name can exist as two separate projects — one in test, one in production — and they never share data or grants. See Environments.

​
Every workflow belongs to a project

Workflows carry a project_id, and the public workflow API uses it directly: 
curl -X POST https://api.retab.com/v1/workflows \
  -H "Authorization: Bearer $RETAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Invoice extraction", "project_id": "proj_…" }'

curl "https://api.retab.com/v1/workflows?project_id=proj_…" \
  -H "Authorization: Bearer $RETAB_API_KEY"
The project_id on a workflow is how access is resolved: grant a person a role on proj_… and they get that access on every workflow whose project_id is proj_….

​
The shared Default Project

Every environment is created with one Default Project (slug default-project). It is the home for workflows that are not deliberately filed under a project of their own — this is the “shared” project.
  • Workflows created without an explicit project land in the Default Project for that environment.
  • To list the organization’s shared workflows, filter GET /v1/workflows?project_id=… with the Default Project’s id.
  • The person who first sets up the environment is granted Project Owner on the Default Project.
Workflows that predate projects may have a null project_id. These are legacy rows from before every workflow was filed under a project; new workflows always belong to one.

​
Managing projects

Projects are created, renamed, and archived from the dashboard. The project management endpoints are dashboard-session only and are not part of the public API. The public API references projects (via project_id on workflows) but does not create them.
  • Create — from the dashboard. The creator is granted Project Owner.
  • Rename / recolor — edit name, description, icon, or color.
  • Archive — a soft delete; the project is marked archived rather than hard-deleted, so history is preserved.

​
Authorization provisioning

When a project is created, its authorization resource is provisioned in the background. Project and workflow responses expose this as authz_status:
authz_statusMeaning
provisioningThe authorization resource is being set up.
readyFully provisioned; access checks are live. (Normal state.)
failedProvisioning failed and will be retried.
deleting / deletedThe project is being torn down.
Under normal operation a project is ready within moments of creation. While provisioning, the creator still sees their own grants optimistically, so there is no lockout window.

​
Where to go next

Roles and permissions

The roles you can grant on a project, and what each one allows.

Access control

How projects fit under organizations and environments.