Workspace Management API
Every action in the Permit.io dashboard is also available through the Permit API, including management of the workspace itself. This reference is for developers who automate Permit workspace setup, for example creating projects and environments or inviting members from a script. It lists the API endpoints for each management task, the API key level each one needs, and links to the full API reference.
For how to authenticate and send requests, see Use the Permit API. For API key levels, see Organization, project, and environment API keys.
Workspace (aka organization)
In the Permit API, a workspace is an organization (org).
| Task | Endpoints | API reference |
|---|---|---|
| Read, update, or delete the workspace | GET, PATCH, DELETE /v2/orgs/{org_id} | Organizations API |
| Invite members and manage their access | GET, POST, DELETE /v2/members; GET, PATCH, DELETE /v2/members/{member_id} | Members API |
| Create, rotate, and delete API keys | GET, POST /v2/api-key; POST /v2/api-key/{api_key_id}/rotate-secret; DELETE /v2/api-key/{api_key_id} | API Keys API |
| Read the log of requests to the Permit API | GET /v2/history | API History API |
| Read the audit log of changes in the workspace | GET /v2/activity | Activity Log API |
The Create Organization API (POST /v2/orgs) requires an API key with an extra permission that Permit adds on request. To request the permission, ask in the Permit Slack community.
For the activity log and API log in the dashboard, see Permit logs.
Projects
The Projects API requires an organization-level (workspace-level) API key.
| Task | Endpoints | API reference |
|---|---|---|
| List and create projects | GET, POST /v2/projects | Projects API |
| Read, update, or delete a project | GET, PATCH, DELETE /v2/projects/{proj_id} | Projects API |
| Give a member access to a project | POST /v2/members with a permission whose object_type is project and whose project_id is the project | Members API |
Environments
The Environments API requires a project-level or organization-level API key.
| Task | Endpoints | API reference |
|---|---|---|
| List and create environments | GET, POST /v2/projects/{proj_id}/envs | Environments API |
| Read, update, or delete an environment | GET, PATCH, DELETE /v2/projects/{proj_id}/envs/{env_id} | Environments API |
| Copy or merge an environment | POST /v2/projects/{proj_id}/envs/{env_id}/copy and /copy/async | Environments API |
| Give a member access to an environment | POST /v2/members with a permission whose object_type is env and whose environment_id is the environment | Members API |
For request samples that create, copy, and merge environments, see Create, copy, and merge environments.
Member permission fields
POST /v2/members invites a member by email (or adds an existing member by id) and grants the listed permissions. Permit sends an invitation to a new member. Each permission has these fields:
| Field | When to set | Values |
|---|---|---|
organization_id | Always (required) | The ID of your workspace |
object_type | Always (required) | org, project, or env |
access_level | Always (required) | admin, write, read, or no_access |
project_id | For project and env permissions | The ID of the project |
environment_id | For env permissions | The ID of the environment |