1. Docs
  2. API Reference
  3. OAuth hosted login: send a work email to its organization's identity provider

OAuth hosted login: send a work email to its organization's identity provider

POST/oauth/sso/start

The single sign-on step of the hosted login page (?method=sso). Looks up the end-user SSO connection that serves the client for the domain of email and, when one does, redirects the browser to that connection's login with the authorization request (state, PKCE code_challenge and nonce) carried along. With no connection for the domain, re-renders the step with the address kept and the reason. Works without JavaScript; the page's script only skips straight here when single sign-on is the address's one way in. Throttled to 20 requests per minute, the lookup's own limit, because an email-to-connection lookup can enumerate domains.

Request body

application/json

emailstring Required
client_idstring Required
redirect_uristring Required
response_typestring Required
scopestring Required
statestring Optional
code_challengestring Required
code_challenge_methodstring Required
noncestring Optional
organizationstring Optional

Responses

text/html

string

The address's domain routes to an end-user SSO connection serving the client: redirect to that connection's login, carrying the authorization request

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Rate limit

20 requests per 1mPer caller: the signed-in user for a bearer token; for an API key, the key and the end user's address when a backend forwards it, otherwise the client address
Request
curl -X POST "https://auth.canopy-io.com/oauth/sso/start" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "string",
    "client_id": "string",
    "redirect_uri": "string",
    "response_type": "string",
    "scope": "string",
    "state": "string",
    "code_challenge": "string",
    "code_challenge_method": "string",
    "nonce": "string",
    "organization": "string"
  }'
Response
Content-Type: text/html

<!doctype html>
<html lang="en">
  <head>…</head>
  <body>
    <!-- The hosted page: its form, any error, and the Environment's branding -->
  </body>
</html>
 Related endpoints Was this page helpful?

Tell us how we can improve this guide.

Canopy