---
title: "Sync a Clerk session to a Framelane workspace"
method: POST
path: "/v1/auth/sync"
tags: ["auth"]
---

# Sync a Clerk session to a Framelane workspace

`POST /v1/auth/sync`

## Request

- Base URL: `https://api.framelane.io`
- URL: `https://api.framelane.io/v1/auth/sync`
- Auth: none declared

Verify a Clerk session token and create, adopt or return the workspace for that Clerk user. On first login a Workspace and initial API key are created and the plaintext key is returned once. If an email-signup workspace already exists for the verified Clerk primary email it is adopted instead, keeping its projects, billing and verified keys. Subsequent logins return the workspace without exposing a key.

## Request body

- AuthSyncRequest
  - `clerk_token` string, required

## Response `200`

Successful Response

- AuthSyncResponse
  - `workspace` WorkspaceOut, required
    - `id` string, required: Unique workspace ID.
    - `name` string, required: Display name for the workspace.
    - `email` string, nullable: Contact email for the workspace owner.
    - `email_verified` boolean: Whether the email address has been verified via OTP.
    - `plan` 'free' | 'pro' | 'enterprise'
    - `plan_status` 'active' | 'past_due' | 'cancelled' | 'trialing'
    - `created_at` string, date-time, required: ISO-8601 UTC timestamp when the workspace was created.
    - `is_admin` boolean: Whether this is an admin workspace, which curates the public template gallery (POST, PATCH and DELETE /v1/templates) and sees its draft listings.
  - `is_new` boolean, required
  - `api_key` ApiKeyCreated: Returned once at creation time -- includes the plaintext secret.
    - `id` string, required: Unique API key ID.
    - `name` string, required: Human-readable label for this key.
    - `key_prefix` string, required: First 8 characters of the key, shown for identification.
    - `created_at` string, date-time, required: ISO-8601 UTC timestamp when this key was created.
    - `last_used_at` string, date-time, nullable: ISO-8601 UTC timestamp of the most recent authenticated request.
    - `revoked_at` string, date-time, nullable: ISO-8601 UTC timestamp when this key was revoked. Null if still active.
    - `key` string, required: Plaintext API key. Store it securely — this is the only time it is returned.

## Other responses

- `401`: Invalid or expired Clerk token.
- `403`: The Clerk primary email is not verified.
- `422`: Validation Error
- `503`: Account setup temporarily unavailable.

---

[API](https://skmtc.dev/framelane/apis/framelane-api.md) · [All operations](https://skmtc.dev/framelane/apis/framelane-api/llms.txt) · [OpenAPI document](https://skmtc.dev/framelane/apis/framelane-api/revisions/a223001ca8e5?raw)