Skip to main content
POST
Email your IT admin a setup link
Owners only: whoever sets up the directory decides everyone’s role.
  • The link works for 30 days and goes only to that address; Pomerado never sees it. Follow their progress with GET /v1/team/sso.
  • A team has one setup email at a time. While an earlier one’s link still works this sends nothing and answers setup_email_active; send replace: true to replace it, and the earlier link stops working. Replacing also removes every earlier address from your team’s WorkOS IT contacts, so only the new one gets WorkOS’s notices.
  • A team sends up to 5 setup emails at once, then one every 12 minutes; past that it answers setup_email_throttled.
  • Callers: an API key, an MCP OAuth token or a Dashboard session.
  • Permission: team:manage; an API key also needs team:manage.
  • Effect: Creates or changes something.
  • Errors: invalid_email, setup_email_active, setup_email_throttled, team_unavailable, role_permission_missing, owner_required, and the errors any request can get.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
email
string
required

Your IT admin's email address, where WorkOS sends the setup link

Maximum string length: 320
replace
boolean

Send a new email even though an earlier one's link still works, which then stops working. Default: false

Response

WorkOS is sending the setup email

email
string
required

Where WorkOS sent the setup email

replaced
boolean
required

Whether it replaced an earlier setup email, whose link stopped working