1. Docs
  2. API Reference
  3. Select an Account from a pre-auth session (multi-Account login)

Select an Account from a pre-auth session (multi-Account login)

POST/v1/auth/select-account

Second step of multi-Account login: exchanges the pre-auth session for an access token bound to the chosen Account's first Application. Guarded by UserJwtGuard with @AllowPreAuth, accepting account_id; the caller must be an active member of that Account or 401 is returned. Entering the Account runs its administrator MFA policy against what the pre-auth token proved: an SSO sign-in into an Account whose after_sso is require answers requires_mfa_challenge with a challenge bound to the Account, an Account that requires a factor the admin lacks answers mfa_enrollment_pending with the session while the grace window lasts and requires_mfa_enrollment with an enrollment continuation after it. Otherwise issues a fresh access and refresh token (Bearer, 900s), sets the refresh and session-marker cookies, and clears the pre-auth cookie; no cookie changes on a refusal. There is no Application picker — switching Apps happens later via switch-application.

Request body

application/json

account_idstring Required

Account ID to bind the new access token to

Responses

application/json

  • dataSelectAccountResponseDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Returned object

SelectAccountResponseDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/v1/auth/select-account" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "string"
  }'
Response
{
  "data": {
    "mfa_enrollment_pending": false,
    "grace_expires_at": "2026-04-20T12:00:00.000Z",
    "requires_mfa_enrollment": false,
    "mfa_enrollment": {
      "enrollment_token": "string",
      "available_factors": [
        "totp"
      ],
      "totp": {
        "otpauth_uri": "string",
        "manual_entry_key": "string"
      }
    },
    "requires_mfa_challenge": false,
    "mfa_challenge": {
      "challenge_token": "string",
      "available_factors": [
        "totp"
      ],
      "expires_at": "2026-04-20T12:00:00.000Z"
    },
    "access_token": "string",
    "token_type": "string",
    "expires_in": 0,
    "account": {
      "id": "string",
      "name": "string",
      "slug": "string"
    },
    "application": {
      "id": "string",
      "name": "string",
      "slug": "string"
    },
    "default_environment_slug": "string"
  }
}
 Related endpoints
POSTRegister a new user
POSTCreate an additional Account for the authenticated admin (no new user)
GETReview the parked account-creation intent before resuming
POSTResume a deferred account creation parked at the register form
DELETEDismiss the parked account-creation intent without creating anything
POSTLook up invite details by token
POSTAccept an invite
POSTAuthenticate and receive tokens
POSTSwitch the active Application in an authenticated session
POSTRefresh access token
POSTLogout and revoke tokens
GETVerify email address
POSTResend verification email
POSTResend verification email by token
POSTRequest password reset
POSTReset password with token
POSTChange password (authenticated)
GETGet current user profile
GETGet current user avatar image
POSTUpload profile avatar
DELETERemove profile avatar
POSTRequest an email-address change
POSTConfirm an email-address change
GETGet current user permissions
GETList the Accounts the current user belongs to
GETList active sessions
DELETERevoke all sessions
DELETERevoke a specific session
 Was this page helpful?

Tell us how we can improve this guide.

Canopy