Figma User Management API Guide

Auth method: Personal Access Token (PAT) or OAuth 2.0

Setup steps

1. Personal Access Token: Log in to Figma → Settings → Account → Personal access tokens → Generate new token. Pass token in header: Authorization: Bearer .
2. OAuth 2.0: Register an app at figma.com/developers/apps to obtain client_id and client_secret. Redirect users to https://www.figma.com/oauth?client_id=...&redirect_uri=...&scope=...&state=...&response_type=code. Exchange authorization code for access token at https://www.figma.com/api/oauth/token via POST with client credentials. Use returned access_token in Authorization: Bearer header.
3. For SCIM: Generate a SCIM API token in the Figma Admin panel (Organization or Enterprise plan required). Use as Bearer token against the SCIM base URL.

Required scopes

Get current authenticated user

• Method: GET
• URL: https://api.figma.com/v1/me
• Watch out for: Returns the user associated with the token only; cannot retrieve arbitrary users via this endpoint.

Request example

GET /v1/me
Authorization: Bearer <token>

Response example

{
  "id": "12345",
  "email": "user@example.com",
  "handle": "jdoe",
  "img_url": "https://..."
}

Get user by ID

• Method: GET
• URL: https://api.figma.com/v1/users/:user_id
• Watch out for: Email is not returned for users other than the authenticated user.

Request example

GET /v1/users/12345
Authorization: Bearer <token>

Response example

{
  "id": "12345",
  "handle": "jdoe",
  "img_url": "https://..."
}

List team members

• Method: GET
• URL: https://api.figma.com/v1/teams/:team_id/members
• Watch out for: Requires the token owner to be a member of the team. Org-level member listing requires org:read scope and Organization/Enterprise plan.

Request example

GET /v1/teams/98765/members
Authorization: Bearer <token>

Response example

{
  "members": [
    {"id":"12345","role":"editor","handle":"jdoe"}
  ]
}

List organization members

• Method: GET
• URL: https://api.figma.com/v1/orgs/:org_id/members
• Watch out for: Organization/Enterprise plan required. Paginated via cursor parameter.

Request example

GET /v1/orgs/11111/members
Authorization: Bearer <token>

Response example

{
  "members": [
    {"id":"12345","email":"user@example.com","role":"admin"}
  ],
  "cursor": "next_cursor_value"
}

SCIM – List users

• Method: GET
• URL: https://www.figma.com/scim/v2/Users
• Watch out for: SCIM token is separate from REST API PAT; generated in Admin panel. Requires Organization or Enterprise plan.

Request example

GET /scim/v2/Users?startIndex=1&count=50
Authorization: Bearer <scim_token>

Response example

{
  "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults":2,
  "Resources":[{"id":"abc","userName":"user@example.com","active":true}]
}

SCIM – Create user

• Method: POST
• URL: https://www.figma.com/scim/v2/Users
• Watch out for: User must have a verified email domain matching the org's claimed domain. Provisioning sends an invite email unless SSO is enforced.

Request example

POST /scim/v2/Users
Authorization: Bearer <scim_token>

{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
 "userName":"user@example.com","active":true}

Response example

{
  "id": "abc123",
  "userName": "user@example.com",
  "active": true
}

SCIM – Update user (deactivate)

• Method: PATCH
• URL: https://www.figma.com/scim/v2/Users/:user_id
• Watch out for: Deactivating a user removes their org seat but does not delete their Figma account or personal files.

Request example

PATCH /scim/v2/Users/abc123
Authorization: Bearer <scim_token>

{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
 "Operations":[{"op":"replace","path":"active","value":false}]}

Response example

{
  "id": "abc123",
  "userName": "user@example.com",
  "active": false
}

SCIM – Delete user

• Method: DELETE
• URL: https://www.figma.com/scim/v2/Users/:user_id
• Watch out for: Behavior may differ from PATCH active=false; verify with Figma docs whether DELETE fully removes org membership or just deprovisions.

Request example

DELETE /scim/v2/Users/abc123
Authorization: Bearer <scim_token>

Response example

HTTP 204 No Content

• Rate limits: Figma enforces rate limits per token. REST API limits are not fully published but documented as 'rate limited' with HTTP 429 responses. SCIM endpoints have separate limits.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: When rate limited, Figma returns HTTP 429. Clients should respect Retry-After header if present and implement exponential backoff. Specific numeric limits are not published in official docs.
• Pagination method: cursor
• Default page size: 0
• Max page size: 0
• Pagination pointer: cursor

• Webhooks available: Yes
• Webhook notes: Figma supports webhooks via the REST API for team-level events. Webhooks are registered per-team and deliver HTTP POST payloads to a configured endpoint.
• Alternative event strategy: No native user-lifecycle webhook events (e.g., user added/removed). Poll /v1/teams/:team_id/members or use SCIM with IdP-driven provisioning for user lifecycle automation.
• Webhook events: FILE_UPDATE, FILE_VERSION_UPDATE, FILE_DELETE, LIBRARY_PUBLISH, FILE_COMMENT

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Organization or Enterprise

• Endpoint: https://www.figma.com/scim/v2

• Supported operations: GET /Users (list users), GET /Users/:id (get user), POST /Users (create/invite user), PATCH /Users/:id (update user attributes, deactivate), DELETE /Users/:id (remove user), GET /Groups (list groups/teams), POST /Groups (create group), PATCH /Groups/:id (update group membership), DELETE /Groups/:id (delete group)

Limitations:

• SCIM token is generated separately from REST API PAT in the Admin panel.
• SAML SSO must be configured before enabling SCIM.
• Deactivating a user (active=false) removes org seat but does not delete the Figma account.
• User email domain must match a domain claimed by the organization.
• Full seat management via SCIM (including editor seat assignment) requires Enterprise plan; Organization plan has basic provisioning.
• March 2025 billing changes may require plan migration for existing customers.

For IdP-driven provisioning, configure SAML SSO first, generate a SCIM token in Admin → Security, and point your IdP (Okta, Entra ID, etc. ) at POST /scim/v2/Users.

The user's email domain must match a domain claimed by the org or provisioning will fail - claim the domain in Admin → Security before attempting bulk provisioning.

For deprovisioning, the IdP sends PATCH /scim/v2/Users/:id with active=false; this removes the org seat but does not delete the user's personal Figma account or files outside the org. Transfer file ownership via the Admin panel before triggering deprovisioning if content continuity matters.

For membership audits via REST, call GET /v1/orgs/:org_id/members with org:read scope and handle cursor-based pagination - pass the cursor value from each response as ? cursor= on the next request until no cursor is returned.

Use SCIM GET /Users for full email visibility, as the REST API omits email for users other than the authenticated token owner.

Provision a new employee via SCIM (IdP-driven)

1. Ensure SAML SSO is configured and SCIM is enabled in Figma Admin panel (Organization or Enterprise plan).
2. Generate a SCIM API token in Admin → Security → SCIM and configure it in your IdP (Okta, Entra ID, etc.).
3. Assign the user to the Figma app in the IdP; the IdP sends POST /scim/v2/Users with userName (email) and name attributes.
4. Figma creates the user and sends an invite email (or auto-provisions if SSO is enforced).
5. Verify user appears in /scim/v2/Users list and in the Figma Admin panel.

Watch out for: If the user's email domain is not claimed by the org, provisioning will fail. Claim the domain in Admin → Security first.

Deprovision a departing employee

1. Remove the user from the Figma app assignment in the IdP.
2. IdP sends PATCH /scim/v2/Users/:id with Operations: [{op: replace, path: active, value: false}].
3. Figma removes the user's org seat; they lose access to org resources.
4. Optionally transfer file ownership via Figma Admin panel before deprovisioning.
5. Confirm user no longer appears as active in /scim/v2/Users.

Watch out for: Deactivation removes org access but does not delete the user's personal Figma account or files outside the org.

Audit current team membership via REST API

1. Generate a PAT or use an OAuth 2.0 token with org:read scope.
2. Call GET /v1/orgs/:org_id/members (Organization/Enterprise) or GET /v1/teams/:team_id/members.
3. Handle cursor-based pagination: check response for cursor field and repeat request with ?cursor= until no cursor is returned.
4. Collect id, email, role fields for each member.
5. Cross-reference with IdP user list to identify orphaned accounts.

Watch out for: Email is only returned in org-level member responses for admins; team member responses may omit email. Use SCIM GET /Users for full email visibility.

The primary integration trap is assuming the REST API and SCIM API are equivalent paths to the same data - they are not.

The REST API does not expose email for users other than the authenticated token owner (/v1/me), making it insufficient alone for building an identity graph that maps Figma accounts to authoritative IdP identities.

SCIM provides email via userName and externalId for IdP correlation, but requires a separately provisioned token and an active SAML SSO configuration; attempting to enable SCIM without SSO in place is not supported.

Rate limits are undocumented numerically for both surfaces - HTTP 429 is returned when exceeded, and clients must implement exponential backoff with Retry-After header handling.

Webhook events are team-scoped and cover only file-level activity; there are no org-level or user-lifecycle webhook events, so user join and leave detection requires polling /v1/orgs/:org_id/members or relying on IdP-side SCIM push. Full SCIM seat management including Editor seat assignment is gated to Enterprise plan; Organization plan supports basic provisioning only.