Project API keys

Mint and manage project API keys (sk_prj_…) with a workspace API key (sk_wsp_…). Project keys authenticate /v1/jobs, /v1/transcriptions, /v1/storage-connections, and /v1/glossary routes — the project is bound to the key automatically. When minting or listing keys with a workspace key, send projectId in the request body (create) or query string (list). Update and delete routes derive the project from apiKeyId. You need a projectId from the Projects API first.

Create a project API keyPOST/v1/project-api-keyschevron_right
List project API keysGET/v1/project-api-keyschevron_right
Update a project API keyPATCH/v1/project-api-keys/{apiKeyId}chevron_right
Revoke a project API keyPATCH/v1/project-api-keys/{apiKeyId}chevron_right
Delete a project API keyDELETE/v1/project-api-keys/{apiKeyId}chevron_right

The Project API key object

apiKeyIdstring: Stable key identifier (key_…).
workspaceIdstring: Owning workspace.
scopestring: Always project for keys under a project.
projectIdstring: Project this key is bound to.
namestring: Human-readable label (1–120 characters).
statusstring: active or revoked. Revoked keys cannot authenticate or be reactivated.
secretMaskedstring: Masked secret prefix/suffix for display. Full secret only on create.
secretstring, optional: Full sk_prj_… secret. Returned only in the create response.
permissionsstring[]: Granted permissions (e.g. job:create, transcript:read, storage_connection:create, webhook:update). Cannot be changed after revoke.
lastUsedAttimestamp | null, optional: Last successful authentication time.
createdBystring: Creator user id or api_key actor.
updatedBystring: Last updater.
createdByUsernamestring | null, optional: Username when created by a user session.
updatedByUsernamestring | null, optional: Username when last updated by a user session.
createdAttimestamp: Creation time.
updatedAttimestamp: Last update time.

{
  "apiKeyId": "key_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "workspaceId": "wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "scope": "project",
  "projectId": "prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "name": "CI runner",
  "status": "active",
  "secretMasked": "sk_prj_....x7K9",
  "permissions": ["job:create", "job:read", "job:list"],
  "lastUsedAt": "2026-05-18T14:00:00Z",
  "createdBy": "api_key",
  "updatedBy": "api_key",
  "createdAt": "2026-05-18T12:34:56Z",
  "updatedAt": "2026-05-18T12:34:56Z"
}

Create a project API key

POST/v1/project-api-keys

Creates a project-scoped API key. The full secret is returned once in data.secret — store it immediately.

Requires permission

project_api_key:create

Parameters

projectIdstring: Target project (prj_…).
namestring: Label for the key (for your logs).
permissionsstring[], optional: Subset of project permissions (e.g. job:create, transcript:read, storage_connection:create, webhook:update). Omit to grant all project permissions.

Returns

Returns the API key metadata plus secret (only on create).

See the the project api key object for attribute details.

curl -X POST "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/project-api-keys" \
  -H "Authorization: Bearer sk_wsp_..." \
  -H "Content-Type: application/json" \
-d '{
  "projectId": "prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "name": "CI runner",
  "permissions": [
    "job:create",
    "job:read",
    "storage_connection:create",
    "storage_connection:read",
    "webhook:read",
    "webhook:update"
  ]
}'

{
  "data": {
  "apiKeyId": "key_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "workspaceId": "wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "scope": "project",
  "projectId": "prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "name": "CI runner",
  "status": "active",
  "secretMasked": "sk_prj_....x7K9",
  "secret": "sk_prj_...(shown once)",
  "permissions": ["job:create", "job:read", "job:list", "transcript:read", "storage_connection:create", "storage_connection:read", "webhook:read", "webhook:update"],
  "lastUsedAt": null,
  "createdBy": "api_key",
  "updatedBy": "api_key",
  "createdByUsername": null,
  "updatedByUsername": null,
  "createdAt": "2026-05-18T12:34:56Z",
  "updatedAt": "2026-05-18T12:34:56Z"
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

List project API keys

GET/v1/project-api-keys

Paginated list of API keys for a project (secrets are never returned).

Requires permission

project_api_key:list

Query parameters

projectIdstring: Project to list keys for (prj_…).
pageinteger: Page number (default 1).
limitinteger: Page size (default 20, max 100).
searchstring, optional: Filter by key name.
statusesstring, optional: Comma-separated: active, revoked.
sortstring, optional: name, status, lastUsed, or created (default).
sortDirstring, optional: asc or desc. Default desc.

curl -G "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/project-api-keys" \
  -H "Authorization: Bearer sk_wsp_..." \
-d "projectId=prj_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
-d "page=1" \
-d "limit=20"

{
  "data": [{
  "apiKeyId": "key_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "workspaceId": "wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "scope": "project",
  "projectId": "prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "name": "CI runner",
  "status": "active",
  "secretMasked": "sk_prj_....x7K9",
  "permissions": ["job:create", "job:read", "job:list"],
  "lastUsedAt": "2026-05-18T14:00:00Z",
  "createdBy": "api_key",
  "updatedBy": "api_key",
  "createdAt": "2026-05-18T12:34:56Z",
  "updatedAt": "2026-05-18T12:34:56Z"
}],
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1",
    "pagination": { "total": 1, "page": 1, "limit": 20, "totalPages": 1, "hasNext": false, "hasPrevious": false }
  }
}

Update a project API key

PATCH/v1/project-api-keys/{apiKeyId}

Updates metadata for a project API key. Typical use: rename with name only. The full secret is never returned again.

Requires permission

project_api_key:update

At least one of name, status, or permissions must be sent.

Parameters

apiKeyIdstring: Key to update.
namestring, optional: New label (1–120 characters).
statusstring, optional: Only revoked is accepted. Sending active returns 422. See also the revoke endpoint.
permissionsstring[], optional: Replace permission list on an active key. Returns 422 on revoked keys.

Returns

Returns the updated Project API key object (no secret).

See the the project api key object for attribute details.

curl -X PATCH "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/project-api-keys/key_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "Authorization: Bearer sk_wsp_..." \
  -H "Content-Type: application/json" \
-d '{
  "name": "CI runner (rotated)"
}'

{
  "data": {
  "apiKeyId": "key_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "workspaceId": "wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "scope": "project",
  "projectId": "prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "name": "CI runner",
  "status": "active",
  "secretMasked": "sk_prj_....x7K9",
  "permissions": ["job:create", "job:read", "job:list"],
  "lastUsedAt": "2026-05-18T14:00:00Z",
  "createdBy": "api_key",
  "updatedBy": "api_key",
  "createdAt": "2026-05-18T12:34:56Z",
  "updatedAt": "2026-05-18T12:34:56Z"
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Revoke a project API key

PATCH/v1/project-api-keys/{apiKeyId}

Revokes a key so it can no longer authenticate. Same route as update — send { "status": "revoked" }. Revocation is permanent.

Requires permission

project_api_key:update

Parameters

apiKeyIdstring: Key to revoke.
statusstring: Must be revoked.

Returns

Returns the API key with status: "revoked". Requests with that secret fail authentication immediately.

See the the project api key object for attribute details.

curl -X PATCH "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/project-api-keys/key_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "Authorization: Bearer sk_wsp_..." \
  -H "Content-Type: application/json" \
-d '{
  "status": "revoked"
}'

{
  "data": {
  "apiKeyId": "key_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "workspaceId": "wsp_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "scope": "project",
  "projectId": "prj_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "name": "CI runner",
  "status": "revoked",
  "secretMasked": "sk_prj_....x7K9",
  "permissions": ["job:create", "job:read", "job:list"],
  "lastUsedAt": "2026-05-18T14:00:00Z",
  "createdBy": "api_key",
  "updatedBy": "api_key",
  "createdAt": "2026-05-18T12:34:56Z",
  "updatedAt": "2026-05-18T15:10:00Z"
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}

Delete a project API key

DELETE/v1/project-api-keys/{apiKeyId}

Permanently removes the key record. Prefer revoke when you need an audit trail.

Requires permission

project_api_key:delete

Parameters

apiKeyIdstring: Key to delete.

Returns

Returns { "apiKeyId", "deleted": true }.

See the the project api key object for attribute details.

curl -X DELETE "https://perchat-media-api-csa4e2e0gedvgyfc.westus-01.azurewebsites.net/v1/project-api-keys/key_01HX2K9V3JEK4WYZN6F0XQ2W8M" \
  -H "Authorization: Bearer sk_wsp_..."

{
  "data": {
  "apiKeyId": "key_01HX2K9V3JEK4WYZN6F0XQ2W8M",
  "deleted": true
},
  "metadata": {
    "requestId": "req_01HX...",
    "responseTime": 42,
    "timestamp": "2026-05-18T12:34:56Z",
    "version": "v1"
  }
}