Skip to content

Get Figma Token Status

Added 2026-08-20

Introduced alongside the move of wf2des generation onto the requesting user's own Figma PAT. A client needs to know whether to prompt for a token before offering Generate, because a missing token fails the generation trigger with an opaque 500 (see POST /wf2des).

Method

REST method is adopted.

HTTP Method

GET: Report whether a Figma Personal Access Token is registered for the authenticated caller.

Naming Convention

Response JSON nodes are camelCase, matching POST /figma/token.

Request and Response

Headers

Request Headers

  • Authorization โ€” required, Cognito JWT
  • Accept
  • Accept-language

Response Headers

  • Content-Type

Get Token Status

URI

GET /figma/token

No path, query, or body parameters. The subject is always the authenticated caller โ€” there is no way to query another user's token state.

Response

The response is JSON.

{
  "registered": true,
  "lastValidatedAt": 1746576000000,
  "updatedAt": 1746576000000
}

Response Fields

Name Type Description
registered boolean true when a row exists for the caller's cognito_sub
lastValidatedAt number | null Epoch ms of the last successful validation against GET https://api.figma.com/v1/me. null when not registered
updatedAt number | null Epoch ms the row was last written. null when not registered

When nothing is registered the endpoint returns 200, not 404:

{
  "registered": false,
  "lastValidatedAt": null,
  "updatedAt": null
}

"No token registered" is a normal state for a user who has not set one up yet, not an error, and a client should render it as a prompt rather than a failure.

The token is never returned

This endpoint reports presence and timestamps only. The stored PAT is write-only by design: echoing it back would turn a write-only secret into a readable one for anyone holding a session. The handler reads through the repository (which decrypts) but returns only metadata.

Authentication

Cognito JWT. The response describes the token belonging to the authenticated cognito_sub.

Error Handling

Description Status Code Status Name
Missing or invalid Cognito JWT 401 Unauthorized
Internal server error 500 Internal Server Error

Processing Flow

  1. Authenticate the caller via Cognito JWT โ€” extract cognito_sub.
  2. Look up the figma_token row for that cognito_sub.
  3. Return registered, lastValidatedAt, updatedAt. Never the token.

Client Guidance

The Figma plugin calls this on the Setup panel to decide between a "token registered" pill and a password field, so a designer can fix the problem in place instead of meeting a 500 at Generate time.

Note that registered: true does not guarantee the token still works โ€” lastValidatedAt records when Figma last accepted it, and a PAT can expire or be revoked afterwards. A stale token surfaces at generation time, and re-registering through POST /figma/token re-validates it.

Related