apiKeys

The methods of pd.apiKeys. Inputs and outputs are described in Conventions; every method can also fail as described in Errors.

Methods

pd.apiKeys.list(input, init?)

List a workspace's API keys

GET /api/workspaces/{workspaceId}/api-keys

Needs api_keys.read. Never returns the key itself: only its prefix, role and lifecycle dates. Revoked and expired keys stay listed (check revokedAt and expiresAt), in no guaranteed order. A revoked or expired key whose role was deleted is listed with roleId null.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.apiKeys.list({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.apiKeys.create(input, init?)

Create an API key

POST /api/workspaces/{workspaceId}/api-keys

Needs api_keys.create. The key is returned once, in this response, and cannot be retrieved again: only a hash of it is stored, so a lost key is replaced, not recovered. It looks like pd_live_ followed by a secret and is sent as Authorization: Bearer <key>. It acts with the permissions of the role it carries, inside this workspace, until it expires or is revoked. A key cannot carry a role that holds a permission the caller lacks: 403 FORBIDDEN, with those permissions in details.permissions. Records an api_keys.created audit entry and answers 201. 409 CONFLICT with details.reason role_deleted when the role is deleted while the key is being made.

Input

Returns 201 Created

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.apiKeys.create({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  body: {
    label: "example",
    roleId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  },
});
console.log(result);

pd.apiKeys.revoke(input, init?)

Revoke an API key

DELETE /api/workspaces/{workspaceId}/api-keys/{keyId}

Needs api_keys.revoke. The key stops authenticating at once; this cannot be undone (create a new key instead). The key stays in the list with revokedAt set. 404 RESOURCE_NOT_FOUND when the key is unknown or already revoked. Records an api_keys.revoked audit entry.

Input

Returns 200 OK

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.apiKeys.revoke({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  keyId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);

pd.apiKeys.rotate(input, init?)

Rotate an API key

POST /api/workspaces/{workspaceId}/api-keys/{keyId}/rotate

Needs both api_keys.create and api_keys.revoke. Issues a new key with the same label, role and expiry and revokes the old one, in one transaction: the old key stops working at once, with no overlap, so deploy the new one right away. The new key is returned once, in this response. The expiry is carried over, not extended. The same rule as creating applies to the key's role: 403 FORBIDDEN when it holds a permission the caller lacks, and the old key is left as it was. 404 RESOURCE_NOT_FOUND when the key is unknown or already revoked; an expired key answers 400 INVALID_REQUEST and is left as it was, and a key whose role was deleted answers 409 CONFLICT with details.reason role_deleted. Records api_keys.created and api_keys.revoked audit entries. Answers 201.

Input

Returns 201 Created

Errors 400 invalid input, 401 missing or invalid key, 403 the key's roles lack the permission, 404 not found, 429 rate limited or out of quota. See Errors.

Example

import { PrismDraft } from "@prism-draft/sdk";

const pd = new PrismDraft({ apiKey: process.env.PRISMDRAFT_API_KEY! });

const result = await pd.apiKeys.rotate({
  workspaceId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
  keyId: "3f0c5a1e-8b2d-4c6e-9a7f-1d2e3f4a5b6c",
});
console.log(result);