From key to first request.
Oroko uses developer keys for public REST and MCP access. Keys act as the Oroko user who created them, so existing workspace and process permissions continue to apply.
1. Create a developer key
In Oroko, open Developer → Keys, give the key a recognisable name and create it. Copy the revealed secret when it is shown and store it securely.
Keep the key secret
Send it only in the X-Oroko-Key header. Do not commit it to a repository or expose it in browser-side code.
2. Verify access
Call GET /me against the production API. A successful response confirms the key and identifies the owning Oroko user.
curl "https://oroko.space/server/oroko-api/api/v1/me" \ -H "X-Oroko-Key: ork_YOUR_KEY"
Then use GET /me/access to inspect the workspace and process access resolved for that user.
Permissions and governance
Developer keys do not create a separate superuser permission model. Requests are evaluated against Oroko's existing access rules. Process writes also remain subject to optimistic revision checks and lifecycle rules, including approved-process locking.
- Workspace membership controls workspace-level access.
- Explicit process access can further restrict what a user can read or edit.
- Review and approval actions use the same governance rules as the Oroko app.
- MCP write tools require explicit confirmation in addition to Oroko permission checks.
Error envelope
REST errors use a structured envelope with a stable error code, a human-readable message and optional details.
{
"error": {
"code": "FORBIDDEN",
"message": "Permission denied",
"details": {}
}
}Common integration errors include invalid developer keys, permission failures, revision conflicts and attempts to modify locked approved processes.
Conventions
- Send JSON request bodies with
Content-Type: application/json. - Use the current process revision for optimistic write operations where required.
- Process deletion is archival rather than permanent deletion.
- Canonical process import/export follows Oroko's v1 process document schema.