Partner SSO (Open in SpitShake)

​

The secret

• It is minted at provisioning and returned once as partner_sso_secret (and on exact idempotent replays).
• Rotate it, or mint the first one for an account provisioned before partner SSO existed, with POST /api/partner/v1/accounts/{id}/sso_secret/rotate. Tokens signed with the old secret are refused at once. A suspended account’s secret can still be rotated, as its API tokens can, so you can answer a leak before reactivating it. An archived account is read-only: rotation answers 409 (account_archived) and changes nothing.

curl -X POST https://spitshake.io/api/partner/v1/accounts/412/sso_secret/rotate \
  -H "Authorization: Bearer $SPITSHAKE_PARTNER_KEY" \
  -H "Idempotency-Key: sso-rotate-2026-10-16"

{
  "account": { "id": 412, "external_id": "firm-8675309" },
  "partner_sso_secret": "5d0c7e9a41b2..."
}

​

The token

​

Sending the user

<form method="post" action="https://spitshake.io/sso/partner" target="_blank">
  <input type="hidden" name="token" value="TOKEN_FROM_YOUR_SERVER">
  <button type="submit">Open in SpitShake</button>
</form>

• Not signed in, or signed in as the same user: SpitShake starts the session and redirects (303) to return_to.
• Signed in as someone else: SpitShake does not switch silently. It shows a page naming the current user and workspace and the one the token is for. Only after the user clicks Continue (a same-origin form with a CSRF token) is the token used and the session switched. The token must still be inside its minute when they click.

​

Minting a token

require "jwt"
require "securerandom"

now = Time.now.to_i
token = JWT.encode(
  {
    iss: "412",                       # the SpitShake account id, as a string
    aud: "spitshake-sso",
    iat: now,
    exp: now + 60,
    jti: SecureRandom.uuid,
    sub: "user_8f3a",                 # your id for the console user
    name: "Ada Lovelace",
    email: "ada@example.com",         # optional
    role: "editor",                   # admin | editor
    return_to: "/templates",
    amr: [ "pwd", "mfa" ]             # optional
  },
  ENV.fetch("SPITSHAKE_SSO_SECRET"),  # the account's partner_sso_secret
  "HS256"
)

import jwt from "jsonwebtoken";
import { randomUUID } from "node:crypto";

// jsonwebtoken sets iat; expiresIn sets exp = iat + 60.
const token = jwt.sign(
  {
    iss: "412",                 // the SpitShake account id, as a string
    aud: "spitshake-sso",
    jti: randomUUID(),
    sub: "user_8f3a",           // your id for the console user
    name: "Ada Lovelace",
    email: "ada@example.com",   // optional
    role: "editor",             // admin | editor
    return_to: "/templates",
    amr: ["pwd", "mfa"],        // optional
  },
  process.env.SPITSHAKE_SSO_SECRET, // the account's partner_sso_secret
  { algorithm: "HS256", expiresIn: 60 }
);

​

Users and roles

• The first sign-in for a sub creates a SpitShake user in that account; later sign-ins with the same sub return to it. The same sub in two accounts is two separate users.
• SSO signs in only users it created itself. It never links to an existing SpitShake user, even one with the same email. Every SSO user’s own SpitShake email is a non-routable placeholder (sso-…@partner-sso.invalid), whatever you send.
• An SSO user signs in only through you. SpitShake refuses their password sign-in and their “Forgot password” requests, answering exactly as it does for an address it does not know, and they cannot set a SpitShake email or password of their own, whatever address they have. Disabling them is how you cut their access.
• The email you send is the user’s contact: SpitShake sends it the mail it would send to the user’s email (security alerts to the account’s admins, and a document they sent being completed or declined). Each sign-in replaces it with the token’s email, and a sign-in without one, or with one that is not a valid address, clears it; with none, that mail is not sent. It is never verified, and it claims nothing: the same address can be another SSO user’s contact, or anyone’s SpitShake email, in any account. SpitShake never finds, signs in or sends a reset link to a user by it.
• A new user is created confirmed, with a random password nobody knows. No welcome, confirmation or password-reset email is sent. Being confirmed gives them nothing beyond SSO: it only matters to password sign-in.
• A first sign-in counts against the plan’s user limit, as an invitation does. When the account is full, the sign-in is refused with 403 and a page that says so; users who already exist still sign in. Size the plan for the users you will send.
• The role follows the token on every sign-in, demotion included, with one exception: the account’s last active admin is never demoted, so the account always has an admin. They stay admin, and the sign-in’s partner.sso_login event records role_not_applied: "last_active_admin". admin and editor map to the same SpitShake roles.
• There is no read-only access. Every SpitShake role can create and send documents, so a token with role: "viewer", with no role, or with any other value is refused rather than signed in with more access than you meant to grant. The refusal page says that read-only access is not available, so you can tell it apart from an expired link. Map your read-only users to no button, or to editor if they should be able to send.
• A user who is archived in SpitShake, or disabled by you, cannot sign in by SSO.
• SpitShake MFA is not asked for: your own sign-in is the gate. Send amr so the audit trail shows how the user authenticated with you.
• Because an SSO user has no password they know, they cannot do what SpitShake confirms with the user’s password: turning off MFA, rotating the identity-handoff secret, or deleting the account. The API answers those requests with 403 and a message that says so (never the 401 of a wrong password, which would send the app to the password sign-in page), and the account settings page shows that message in place of its delete button. An admin who signs in with a password does those.

​

Disabling a user

# One account
curl -X DELETE https://spitshake.io/api/partner/v1/accounts/412/sso_users/user_8f3a \
  -H "Authorization: Bearer $SPITSHAKE_PARTNER_KEY"

# Every account you manage
curl -X DELETE https://spitshake.io/api/partner/v1/sso_users/user_8f3a \
  -H "Authorization: Bearer $SPITSHAKE_PARTNER_KEY"

{
  "subject": "user_8f3a",
  "account_id": 412,
  "user_id": 991,
  "found": true,
  "disabled": true,
  "already": false,
  "sessions_ended": true,
  "sessions_purged": 1,
  "session_purge_failed": false,
  "tokens_revoked": 0,
  "oauth_tokens_revoked": 0
}

{
  "subject": "user_8f3a",
  "accounts_affected": [412, 413],
  "accounts": [
    { "account_id": 412, "user_id": 991, "found": true, "disabled": true, "already": false, "...": "..." },
    { "account_id": 413, "user_id": 1007, "found": true, "disabled": true, "already": false, "...": "..." }
  ]
}

​

Refusals

​

Rate limits