---
title: "Authenticate user with credentials"
method: POST
path: "/userAccount/authenticate"
tags: ["User Account"]
---

# Authenticate user with credentials

`POST /userAccount/authenticate`

Authenticate a user using the specified method and credentials.
Requires a valid session token from `/initAuth`.

**Credential Formats by Method:**

- `password`: `{ "credentials": { "password": "your-password" } }`
- `otp`: `{ "credentials": { "otp": "123456" } }` (6-digit code, valid for 10 minutes)
- `google`: `{ "credentials": "google-id-token-string" }`
- `microsoft`: `{ "credentials": { "accessToken": "...", "idToken": "..." } }`
- `azureAd`: `{ "credentials": { "accessToken": "...", "idToken": "..." } }`
- `oauth`: `{ "credentials": { "accessToken": "...", "idToken": "..." } }`
- `samlSso`: Handled via redirect flow (use `/saml/signIn` instead)

**Multi-Step Response:**

If organization uses MFA, successful authentication returns:
- `status: "success"` with `nextStep` and `allowedMethods` for next step

**Fully Authenticated Response:**

After completing all steps:
- `message: "Fully authenticated"` with `accessToken` (1hr) and `refreshToken` (7d)

**Security:**

- Account locks after 5 consecutive failed attempts
- CAPTCHA may be required if enabled (pass `cf-turnstile-response`)

## Headers

- `x-session-token` string, required

## Request body

- AuthenticateRequest — Request to authenticate using specified method. **Credential format varies by method:** - `password`: `{ password: "string" }` - `otp`: `{ otp: "123456" }` (6-digit code) - `google`: `"google-id-token-string"` - `microsoft`: `{ accessToken: "...", idToken: "..." }` - `azureAd`: `{ accessToken: "...", idToken: "..." }` - `oauth`: `{ accessToken: "...", idToken: "..." }` - `samlSso`: handled via redirect flow
  - `method` 'samlSso' | 'otp' | 'password' | 'google' | 'microsoft' | 'azureAd' | 'oauth', required — Authentication method to use
  - `credentials` union, required — Credentials based on the authentication method
    - PasswordCredentials — Credentials for password authentication
      - `password` string, password, required — User password
    - OtpCredentials — Credentials for OTP authentication
      - `otp` string, required — 6-digit one-time password
    - OAuthCredentials — Credentials for OAuth authentication (Microsoft, Azure AD, generic OAuth)
      - `accessToken` string, required — OAuth access token
      - `idToken` string — OAuth ID token (JWT)
    - string — Google ID token (for google method)
  - `email` string, email — Optional email for verification (used with some OAuth methods)
  - `cf-turnstile-response` string — Cloudflare Turnstile CAPTCHA token (optional, if CAPTCHA is enabled)

## Response `200`

Authentication step successful or fully authenticated

- union — Either the next step in a multi-factor flow (`status`, `nextStep`, `allowedMethods`, `authProviders`) or final tokens (`message`, `accessToken`, `refreshToken`).
  - AuthenticateMultiStepResponse — Current authentication step succeeded; additional MFA steps remain
    - `status` 'success', required — Step completion status
    - `nextStep` integer, required — Next authentication step index
    - `allowedMethods` string[], required — Allowed method types for the next step
    - `authProviders` AuthProviders, required — Configuration for external authentication providers (returned when those methods are allowed)
      - `google` AuthProviderGooglePublicConfig — Public Google OAuth settings returned to clients
        - `clientId` string — Google OAuth client ID
        - `enableJit` boolean — Whether just-in-time user provisioning is enabled for Google
      - `microsoft` AuthProviderMicrosoftPublicConfig — Public Microsoft OAuth settings returned to clients
        - `tenantId` string — Microsoft tenant ID
        - `clientId` string — Microsoft OAuth client ID
        - `enableJit` boolean — Whether just-in-time user provisioning is enabled for Microsoft
      - `azuread` AuthProviderAzureAdPublicConfig — Public Azure AD OAuth settings returned to clients
        - `tenantId` string — Azure AD tenant ID
        - `clientId` string — Azure AD client ID
        - `enableJit` boolean — Whether just-in-time user provisioning is enabled for Azure AD
      - `oauth` AuthProviderOAuthPublicConfig — Public generic OAuth provider settings returned to clients
        - `providerName` string, required — Custom OAuth provider display name
        - `clientId` string, required — OAuth client ID
        - `tokenEndpoint` string, required — OAuth token endpoint URL
        - `authorizationUrl` string, required — OAuth authorization URL
        - `clientSecret` string — Client secret (omitted when stripped for public responses)
        - `userInfoEndpoint` string — UserInfo endpoint URL
        - `scope` string — Default OAuth scopes
        - `enableJit` boolean — Whether just-in-time user provisioning is enabled for this provider
      - `saml` object — Present when SAML SSO is an allowed method; may be an empty object
  - AuthenticateFinalResponse — All authentication steps complete; JWT tokens returned
    - `message` string, required — Success message
    - `accessToken` string, required — JWT access token (1 hour expiry)
    - `refreshToken` string, required — JWT refresh token (7 days expiry)

## Other responses

- `400` — Invalid request, method not allowed, invalid credential format or Account blocked due to too many failed attempts (5 attempts max)
- `401` — Invalid credentials (wrong password, expired OTP, etc.)
- `404` — Session expired or user not found
- `410` — OTP has expired (valid for 10 minutes)
- `500` — Internal server error

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)