1. Docs
  2. API Reference
  3. Identity multi-App login: complete Application selection from pre-auth session

Identity multi-App login: complete Application selection from pre-auth session

POST/v1/identity/auth/select-application

Request body

  • account_idstring*

    Account ID the Application belongs to

  • application_idstring*

    Application ID to bind the new access token to

Code samples

cURLJavaScriptPythonGo
curl -X POST "https://api.canopy.dev/v1/identity/auth/select-application" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "string",
    "application_id": "string"
  }'

Responses

200 Identity tokens returned bound to the selected Application + its default Environment
{
  "requires_application_selection": false,
  "requires_mfa_challenge": false,
  "expires_in": 0,
  "identity": {
    "id": "string",
    "email": "string",
    "first_name": "string",
    "last_name": "string"
  },
  "access_token": "string",
  "token_type": "string",
  "applications": [
    {
      "id": "string",
      "name": "string",
      "slug": "string"
    }
  ],
  "mfa_challenge": {
    "challenge_token": "string",
    "available_factors": [
      "totp"
    ],
    "expires_at": "2026-04-20T12:00:00.000Z"
  },
  "mfa_enrollment_pending": false,
  "grace_expires_at": "2026-04-20T12:00:00.000Z"
}

application/json

  • requires_application_selectionboolean*
  • requires_mfa_challengeboolean*

    True when the env requires MFA and the identity has ≥ 1 enrolled factor. The client must POST one of `/v1/identity/auth/mfa/challenge/*` with the supplied `mfa_challenge.challenge_token` to mint a session.

  • expires_innumber*
  • identityIdentityUserDto*
  • access_tokenstring
  • token_typestring
  • applicationsIdentityApplicationSummaryDto[]
  • mfa_challengeIdentityMfaChallengePromptDto
  • mfa_enrollment_pendingboolean

    True when the env requires MFA, the identity has not yet enrolled a factor, and the per-env grace timer has time on it. Session is fully issued; the client should nudge the user to enroll a factor before `grace_expires_at`.

  • grace_expires_atstring (date-time)

    Wall-clock deadline by which the identity must enroll a factor; after this, login is blocked with `mfa.enrollment_required` until an admin force-resets MFA.

401 Invalid or expired token
403 This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa)

Returned object

On this page

Related endpoints

POSTAuthenticate identity and receive tokens
POSTRefresh identity access token
POSTLogout identity and revoke tokens
POSTVerify identity email address
POSTResend identity verification email
POSTRequest identity password reset
POSTReset identity password with token
POSTChange identity password (authenticated)
GETGet current identity profile
GETList identity active sessions
DELETERevoke a specific identity session
POSTLook up invite details by token
POSTAccept an invite