1. Docs
  2. API Reference
  3. Authenticate identity and receive tokens

Authenticate identity and receive tokens

POST/v1/identity/auth/login

Request body

  • account_slugstring*

    Account slug (URL-safe identifier; usually derived from the host or the OAuth client). See PLAN.md Decision 13.

  • emailstring*

    Identity email address

  • passwordstring*

    Identity password

Code samples

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

Responses

200 Tokens returned
{
  "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.

Returned object

On this page

Related endpoints

POSTIdentity multi-App login: complete Application selection from pre-auth session
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