Get Access Tokens

The SSO API allows external systems (e.g., SharePoint, intranet portals) to generate one-time login tokens. These tokens let users access Wortfreunde Studio directly, without entering credentials, by appending a ?sso=TOKEN parameter to any Studio URL.

Prerequisites

• An API token with the write:sso scope (create one here)
• The account and team IDs for your Studio instance (found on the API Tokens page under Settings → API Tokens)

Create an SSO Token

POST /sso_tokens

Request Body

{
  "email": "[jane.doe@example.com](mailto:jane.doe@example.com)",
  "first_name": "Jane",
  "last_name": "Doe"
}

Field	Type	Required	Description
email	string	Yes	Email address of the user
first_name	string	Yes	First name (only used when creating a new user)
last_name	string	Yes	Last name (only used when creating a new user)

⚠️ Warnung

If a user with this email already exists, first_name and last_name are ignored, the existing name is preserved.

Example Request

curl -s -X POST "https://api.wortfreunde.ch/v1/sso_tokens" \
  -H "Authorization: Bearer $WORTFREUNDE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[jane.doe@example.com](mailto:jane.doe@example.com)", "first_name": "Jane", "last_name": "Doe"}' \
  | python3 -m json.tool

Response

Status: 201 Created

{
  "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w",
  "user_created": true
}

Field	Type	Description
token	string	One-time login token (URL-safe, 43 characters)
user_created	boolean	true if a new user was created, false if an existing user was found

Error Responses

Code	Error Code	Description
401	missing_token	Missing or invalid API key
403	-	Token lacks write:sso scope
422	parameter_missing	Missing required field (email, first_name, or last_name)

---

SSO Login Flow

1. Request: Your system calls POST /sso_tokens with the user's email and name
2. Provisioning: Wortfreunde finds the user by email, or creates a new account with editor role
3. Token: A one-time token is returned (valid for 5 minutes)
4. Redirect: Your system redirects the user's browser to any Studio URL with the token appended: https://studio.wortfreunde.ch/client/123/t/42/posts?sso=TOKEN
5. Login: Wortfreunde validates and consumes the token, signs the user in, and redirects to the clean URL (without ?sso=)

⚠️ Warnung

Security: Tokens are single-use and expire after 5 minutes. Once consumed or expired, the token cannot be reused. Always generate a fresh token for each login attempt.

User Roles

Scenario	Role Assigned
New user (email not found)	editor, limited access to posts and ideas
Existing user, not yet in this account	editor, added to account with limited access
Existing user, already in account	Unchanged, keeps their current role

Info

The editor role provides limited access. Editors can view and edit posts and ideas but cannot create, delete, or publish content. They do not have access to other sections like areas, topics, templates, or settings. Account administrators can change the role at any time under Settings → Team.

Example: SharePoint Integration

// SharePoint Flow: Generate SSO token and redirect user
async function openWortfreunde(userEmail, firstName, lastName, targetPath) {
  const response = await fetch('https://api.wortfreunde.ch/v1/sso_tokens', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: userEmail,
      first_name: firstName,
      last_name: lastName
    })
  });

  const { token } = await response.json();

  // Redirect the user to Wortfreunde Studio
  window.open(
    `https://studio.wortfreunde.ch${targetPath}?sso=${token}`
  );
}

Next Steps

• Chromeless Mode: embed Studio pages without navigation, ideal for combining with SSO