Check which sign-in methods an email can use

Overview

Find out whether an email address signs in with a password, SSO, or both. An unknown email gets the same answer as a password-only user, so it doesn't reveal whether a password-only account exists.

Use this on a sign-in screen to route the user to the right method.

You'll need the email.

Returns the available methods. When JumpCloud is one of them, sso_url is the JumpCloud: start sign-in URL to send the browser to.

Prerequisites

• None.

Base URL

Endpoint

POST /api/v1/auth/discover

Authentication

Public (no token)

• No token is needed. Send the email address the user typed.

Rate limit

10 requests per minute, counted per client IP address. The count is shared with the other sign-in routes in the same group (login, verify/email/otp), and over the limit the API returns 429 with {"message": "Too Many Attempts."}.

Request parameters

None.

Request body

Request payload

{
  "email": "[email protected]"
}

Response body

The payload is inside data.

Response payload

{
  "data": {
    "methods": [
      "password",
      "jumpcloud"
    ],
    "preferred": "password",
    "sso_url": "https://production-api.shoutaboutus.com/api/v1/auth/sso/jumpcloud/redirect"
  }
}

Examples

Success payload

A user who must use SSO:

{
  "data": {
    "methods": [
      "jumpcloud"
    ],
    "preferred": "jumpcloud",
    "sso_url": "https://production-api.shoutaboutus.com/api/v1/auth/sso/jumpcloud/redirect"
  }
}

A password-only user, or an unknown email:

{
  "data": {
    "methods": [
      "password"
    ],
    "preferred": "password",
    "sso_url": null
  }
}

Error payload

422 email missing

{
  "message": "The email field is required.",
  "errors": {
    "email": [
      "The email field is required."
    ]
  }
}

422 Not an email address

{
  "message": "The email field must be a valid email address.",
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ]
  }
}

429 Too many requests

{
  "message": "Too Many Attempts."
}

Example request

curl --request POST \
  --url "https://production-api.shoutaboutus.com/api/v1/auth/discover" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"email": "[email protected]"}'