Platform API reference

Platform API · Platform-Api-Keys

post/v1/workspaces/{workspace_slug}/api-keys/previewAuth

Describe the key a mint with this `preset` or these `policy_ids` would create, without creating anything: what it could do in plain sentences, and whether you may mint it. Read-only, so it takes no `Idempotency-Key`. Powers the review step of the console key wizard.

Path parameters

workspace_slug*string

Slug of the workspace. Platform routes name the workspace by slug, positionally in the SDK (`platform.workspaces.retrieve("acme")`); the product APIs bind `workspace_id` instead.

Request body

policy_idsarray

Managed policy ids the key would bind. Send exactly one of `policy_ids` and `preset`.

Example: ["11111111-1111-1111-1111-111111111111"]

presetenum (9)

The ready-made permission set the key would use. Send exactly one of `policy_ids` and `preset`.

Example: "readonly"

Response · 200

allowed*array

What the key would be able to do, one plain sentence per action, as `<Product>: <action>` — the same sentences `GET /v1/api-keys/self` returns for a minted key. A sentence ends in `(only some resources)`, `(with exceptions)` or `(with conditions)` when the policy narrows it. Empty when the key could do nothing.

Example: ["Mail: Read domains and templates","Mail: Send email from your verified domains"]

actions*array

The permission catalog actions behind `allowed`, in the same order.

Example: ["mail.read","mail.send"]

grantable*boolean

Whether you may mint this key. `false` when it would hold an action you do not hold yourself; minting it would then fail with 403.

refusal*string

Why a mint would be refused, when `grantable` is `false`; otherwise `null`.

Example: null

Example

Request

POST https://api.platform-auth.productcraft.co/v1/workspaces/{workspace_slug}/api-keys/preview
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "policy_ids": [
    "11111111-1111-1111-1111-111111111111"
  ],
  "preset": "readonly"
}

Response

{
  "allowed": [
    "Mail: Read domains and templates",
    "Mail: Send email from your verified domains"
  ],
  "actions": [
    "mail.read",
    "mail.send"
  ],
  "grantable": false,
  "refusal": null
}