API Keys

Create a scoped API key

Create a new posterly API key for the authenticated user after explicit confirmation. The calling token must be a dashboard-created API key with accounts:write. OAuth-issued tokens, managed assistant tokens, and session-authenticated requests cannot mint API keys. Requested scopes cannot exceed the scopes on the calling key. A teammate whose API access comes from a workspace owner gets a key bound to that workspace (pass workspace_id when there are several; otherwise 400 workspace_id_required). Those keys count against the owner plan, per teammate per workspace, and the owner is emailed. The full key is returned once in the key field.

post/api/v1/api-keys

Request

  • Base URL: https://www.poster.ly
  • URL: https://www.poster.ly/api/v1/api-keys
  • Auth: HTTP bearer

Request body

namestring

Human-readable key name.

scopesApiKeyScope[]

Scopes for the new key. Omit to copy the calling key scopes. Requested scopes cannot exceed the calling key scopes. billing:read and billing:write allow managing the posterly subscription (cancel/pause/resume/downgrade). review_links:write is never inherited and cannot be requested here: it is granted only when a person ticks "Create client portal sign-in links" in /dashboard/api. The same applies to members:read and members:write, granted only by the "Manage team" permission.

workspace_idstring

Optional workspace restriction. Workspace-scoped calling keys cannot create keys outside their workspace.

expires_in_daysinteger

Optional expiry from now, up to 365 days. Omit for no expiry.

confirmtrue required

Must be true after the user explicitly confirms that a new secret API key should be created.

Example request

{
  "name": "Poke agent key",
  "scopes": [
    "accounts:read",
    "posts:read",
    "posts:write"
  ],
  "expires_in_days": 90,
  "confirm": true
}

Response

API key created successfully. Store the returned key securely; it will not be shown again.

keystring required

Full API key. This is only returned once.

warningstring

Example response

{
  "key": "pst_live_abcd1234...",
  "api_key": {
    "id": "6e1a2b76-9f41-4d6d-a4c8-13d70f89bb31",
    "name": "Poke agent key",
    "key_prefix": "pst_live_abcd",
    "scopes": [
      "accounts:read",
      "posts:read",
      "posts:write"
    ],
    "workspace_id": null,
    "expires_at": null,
    "created_at": "2026-06-06T12:00:00.000Z"
  },
  "warning": "This is the only time the full API key is returned. Store it securely and never paste it into public chats or client-side code.",
  "limits": {
    "tier": "starter",
    "max_user_keys": 1,
    "active_user_keys": 1,
    "remaining_user_keys": 0,
    "uses_grandfathered_keys": false
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.