Planable Authentication

generated: '2026-08-13'
method: searched
source: https://planable.io/guides/planable-public-api/
derived_from: openapi/_original/planable-openapi.json
docs:
  - https://planable.io/guides/planable-public-api/
  - https://help.planable.io/hc/en-us/articles/27638359236508-How-to-connect-and-use-the-Planable-Public-API
  - https://planable.io/guides/planable-mcp/
summary:
  types:
    - http
    - oauth2
  surfaces: 2
schemes:
  - name: bearerAuth
    surface: rest
    type: http
    scheme: bearer
    bearerFormat: pln_*
    applied: 'globally — every one of the 51 published operations carries security: [{bearerAuth: []}]'
    header: 'Authorization: Bearer pln_your_token_here'
    base_url: https://api.planable.io/api/v1
    scopes: [read, write]
    scope_note: >-
      Scope is not an OAuth scope parameter; it is a property chosen when the token is minted in
      Company settings. The OpenAPI does annotate per-operation intent as
      `security: [{bearerAuth: ["read"]}]` / `["write"]`, which is the only machine-readable
      signal of which scope an operation needs.
    plan_gate: >-
      New tokens can only be generated by companies on the Pro and Enterprise plans; tokens
      already generated keep working regardless of plan (stated in info.description of the spec).
    provisioning:
      path: Profile settings -> Integrations -> Public API -> Generate tokens (lands in Company settings -> API tokens)
      required_role: Company Owner or Administrator
      fields: [Name, Scopes, Workspaces, Expiry]
      expiry_options: [30 days, 60 days, 90 days, 6 months, 1 year, Never]
      max_active_tokens_per_company: 10
    failure_modes:
      - status: 401
        code: UNAUTHORIZED
        meaning: Missing, invalid or expired token.
        observed: 'Anonymous GET https://api.planable.io/api/v1/ping returned {"error":{"code":"UNAUTHORIZED","message":"Missing Authorization header","requestId":"..."}}'
      - status: 403
        code: FORBIDDEN
        meaning: Scope or workspace-access violation — a read token attempting a write, or a token restricted away from the target workspace.
    sources:
      - openapi/_original/planable-openapi.json
  - name: mcpOAuth
    surface: mcp
    type: oauth2
    flow: authorization_code
    pkce: S256
    resource: https://mcp.planable.io/mcp
    issuer: https://mcp.planable.io/
    authorization_endpoint: https://mcp.planable.io/oauth/authorize
    token_endpoint: https://mcp.planable.io/oauth/token
    revocation_endpoint: https://mcp.planable.io/oauth/revoke
    registration_endpoint: https://mcp.planable.io/oauth/register
    dynamic_client_registration: true
    token_endpoint_auth_methods: [client_secret_post, none]
    scopes: [read, approve, edit, publish, analyze, engage]
    session:
      inactivity_expiry: 8 hours, auto-refresh
      authorization_validity: 180 days
      per_user: true
    plan_gate: available on all Planable plans (unlike the REST API)
    detail: scopes/planable-scopes.yml
    sources:
      - well-known/planable-oauth-authorization-server.json
      - well-known/planable-oauth-protected-resource.json
security_guidance_published:
  - Treat tokens like passwords; never paste one into a document, a Slack message or a Git repository.
  - Store tokens in a password manager.
  - Use read-only scope wherever the integration allows it.
  - Restrict a token to the specific workspaces it needs.
  - Revoke immediately on suspected exposure and generate a new token.
x-evidence:
  fetched: '2026-08-13'
  probes:
    - url: https://api.planable.io/api/v1/ping
      http_status: 401
    - url: https://mcp.planable.io/mcp
      http_status: 401
      www_authenticate: 'Bearer error="invalid_token"'
    - url: https://planable.io/guides/planable-public-api/
      http_status: 200