> ## Documentation Index > Fetch the complete documentation index at: https://docs.praxis-ai.com/llms.txt > Use this file to discover all available pages before exploring further. # Sign in with Apple (native) > Native (iOS app) Sign in with Apple. Verifies `identityToken` against Apple's public JWKS, then resolves the user by `appleSub` first, falling back to a verified-email match, and finally creates a new account — then completes through the same `autosignup` → `signin` pipeline as `/api/auth/autosignup`, so the response shape, email-MFA challenge, and branding switch all behave exactly as they do there. No OTP round-trip: the identity token itself is the assertion (see `docs/index/oauth-otp.md`). **Resolution order:** 1. A user already carrying this `appleSub` → that user signs in (name/email untouched). 2. No `appleSub` match → the token must carry a verified email (`email_verified === true`, checked before any lookup, so an unverified caller learns nothing about existing data) — a user already found at that email with a DIFFERENT `appleSub` is a conflict; otherwise the Apple id is linked onto that user. 3. Nothing matches → a new account is created, named from `fullName` when present. **Security:** - Rate limited via `authLimiter` (100 requests/minute/IP). - The verified Apple identity travels on a trusted, non-enumerable request marker — never a body field — so the public shape this route forwards to `autosignup` cannot be forged by POSTing the same fields to `/api/auth/autosignup` directly. - Do not send `lticontextid` — it is never forwarded, and would misroute this into SDK-launch handling if it were. ## OpenAPI ````yaml /mdx/api-reference/admin/admin-api.json post /api/auth/apple openapi: 3.0.0 info: title: Pria Admin API version: 2.0.73 description: >- Pria API Documentation Praxis's developer platform is a core part of our mission to empower organizations to grow better. Our APIs are designed to enable teams of any shape or size to build robust integrations that help them customize and get the most value out of Pria. All Pria APIs are built using REST conventions and designed to have a predictable URL structure.

They use many standard HTTP features, including methods (POST, GET, PUT, DELETE) and error response codes.

All API calls are made under https://hiimpria.ai/api and all responses return standard JSON. In these docs, you'll find lists of all available endpoints for a given API, along with interactive code blocks for building requests. For walkthroughs of basic usage for these APIs, check out the API guides. servers: - url: https://pria.praxislxp.com description: Pria API Server security: [] tags: - name: Authentication description: User authentication, registration, and password management (/api/auth) - name: OAuth description: OAuth authentication providers - Google, GitHub, SSO (/api/auth/oauth) - name: User description: User profile management and account operations (/api/user) - name: User Institutions description: User institution memberships and switching (/api/user/institution) - name: User Tools description: Available tools for authenticated users (/api/user/tools) - name: Institutions description: Institution settings and configuration (/api/user/institution) - name: Conversation description: AI conversation and Q&A endpoints (/api/ai) - name: Realtime description: Real-time voice AI and WebRTC sessions (/api/ai/rt) - name: Assistant description: AI assistant configuration and management (/api/user/assistant) - name: History description: Conversation history and favorites (/api/user/history) - name: RAG description: >- Document upload, embedding, and retrieval-augmented generation (/api/user/files, /api/user/rag) - name: Setting description: Instance variables and settings management (/api/user/setting) - name: Branding description: Digital twin branding and customization (/api/agent/branding) - name: Agent description: Agent engagement and session management (/api/agent) - name: SDK Launch description: >- SDK launch token signing and verification for secure iframe embedding (/api/auth/sdk-sign, /api/auth/sdk-verify) - name: Testing description: Health checks, diagnostics, and test endpoints (/api/test) - name: Admin Accounts description: Account management for super admins (/api/admin/account) - name: Admin Institutions description: Institution management for admins (/api/admin/institution) - name: Admin Users description: User management for admins (/api/admin/user) - name: Admin Entitlements description: >- User-institution relationships and permissions (/api/admin/userInstitution) - name: Admin Sessions description: Session management for admins (/api/admin/session) - name: Admin Histories description: Conversation history management and analytics (/api/admin/history) - name: Admin Assistants description: AI assistant management for admins (/api/admin/assistant) - name: Admin Questions description: Institution question and prompt management (/api/admin/question) - name: Admin Tools description: Tool configuration management (/api/admin/tool) - name: Admin AI Models description: AI model configuration (/api/admin/aimodel) - name: Admin MCP Servers description: Model Context Protocol server management (/api/admin/mcpserver) - name: Admin Feedbacks description: User feedback management (/api/admin/feedback) - name: Admin Uploads description: Upload management (/api/admin/upload) - name: Admin Charts description: Analytics and visualization chart management (/api/admin/chart) - name: Admin Memory description: Admin inspection and editing of user/instance memory parameters. - name: Admin Usage Limits description: Per-user usage-vs-cap reporting and account-wide at-limit counts. paths: /api/auth/apple: post: tags: - Authentication summary: Sign in with Apple (native) description: > Native (iOS app) Sign in with Apple. Verifies `identityToken` against Apple's public JWKS, then resolves the user by `appleSub` first, falling back to a verified-email match, and finally creates a new account — then completes through the same `autosignup` → `signin` pipeline as `/api/auth/autosignup`, so the response shape, email-MFA challenge, and branding switch all behave exactly as they do there. No OTP round-trip: the identity token itself is the assertion (see `docs/index/oauth-otp.md`). **Resolution order:** 1. A user already carrying this `appleSub` → that user signs in (name/email untouched). 2. No `appleSub` match → the token must carry a verified email (`email_verified === true`, checked before any lookup, so an unverified caller learns nothing about existing data) — a user already found at that email with a DIFFERENT `appleSub` is a conflict; otherwise the Apple id is linked onto that user. 3. Nothing matches → a new account is created, named from `fullName` when present. **Security:** - Rate limited via `authLimiter` (100 requests/minute/IP). - The verified Apple identity travels on a trusted, non-enumerable request marker — never a body field — so the public shape this route forwards to `autosignup` cannot be forged by POSTing the same fields to `/api/auth/autosignup` directly. - Do not send `lticontextid` — it is never forwarded, and would misroute this into SDK-launch handling if it were. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AppleSignInRequest' responses: '200': description: > Signed in (or newly created and signed in). Same union as `/api/auth/signin`: either `{ token, profile }`, or `{ mfaRequired: true, challengeId, factor, availableFactors, maskedEmail }` when the resolved user has email MFA enabled — discriminate on `mfaRequired === true` and complete via `POST /api/auth/mfa-verify`. content: application/json: schema: $ref: '#/components/schemas/SignInResponse' '400': description: > `APPLE_TOKEN_INVALID` (malformed token, bad signature, unknown signing key, absent `sub`), `APPLE_TOKEN_EXPIRED` (Apple's own `exp` has passed), `APPLE_AUDIENCE_MISMATCH` (token minted for a different bundle id / Services ID), `APPLE_NONCE_MISMATCH` (missing `nonce`, or none of its accepted forms match the token's `nonce` claim), or `APPLE_SIGNIN_FAILED` (generic fallback — an unexpected failure downstream of resolution). content: application/json: schema: $ref: '#/components/schemas/AppleSignInError' '409': description: > `APPLE_EMAIL_REQUIRED` (no `appleSub` match and Apple did not share an email — the user must remove and re-add Pria under Settings › Apple ID › Sign in with Apple), `APPLE_EMAIL_UNVERIFIED` (Apple has not verified the email on this Apple ID), or `APPLE_ACCOUNT_CONFLICT` (the resolved email already belongs to a user linked to a DIFFERENT Apple id — sign in the way that account usually does instead). content: application/json: schema: $ref: '#/components/schemas/AppleSignInError' '503': description: > `APPLE_JWKS_UNAVAILABLE` (Apple's signing-key endpoint could not be reached or returned no usable keys — retry shortly) or `APPLE_NOT_CONFIGURED` (neither `APPLE_BUNDLE_ID` nor `APPLE_SERVICES_ID` is set on this server). content: application/json: schema: $ref: '#/components/schemas/AppleSignInError' components: schemas: AppleSignInRequest: type: object required: - identityToken - nonce properties: identityToken: type: string description: > The Apple identity token as delivered by `ASAuthorizationAppleIDCredential.identityToken` (a UTF-8 string, not the raw bytes) — a short-lived RS256 JWT signed by Apple. Verified against Apple's public JWKS (signature, issuer, audience allowlist, expiry); the raw Apple private key is never involved. Single-use in spirit (10-minute validity) — do not cache it client-side. example: >- eyJraWQiOiJXNldjT0tCIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwczovL2FwcGxlaWQuYXBwbGUuY29tIiwic3ViIjoiMDAxMjM0LmFiY2RlZi4xMjM0IiwiYXVkIjoiY29tLnByYXhpcy5wcmlhIiwiZXhwIjoxNzU3NTAwMDAwLCJpYXQiOjE3NTc0OTk0MDAsIm5vbmNlIjoiYWJjMTIzIiwiZW1haWwiOiJqYW5lLmRvZUBwcml2YXRlcmVsYXkuYXBwbGVpZC5jb20iLCJlbWFpbF92ZXJpZmllZCI6InRydWUiLCJpc19wcml2YXRlX2VtYWlsIjoidHJ1ZSJ9.signature nonce: type: string description: > Required (not optional — a replay control that can be skipped is not one). The RAW nonce the app generated for this sign-in attempt; the app sends Apple a SHA-256 digest of this same value. The server accepts the raw nonce or its SHA-256 as hex, base64 or base64url, matched against the `nonce` claim inside `identityToken`. example: f3a1c9e2b6d4 fullName: type: object nullable: true description: > Apple sends this ONLY on the very first authorization for a given Apple ID + app pair — send it whenever the native SDK callback provides it, or the account is created nameless (Apple will not resend it later without the user removing and re-granting the app). Ignored entirely when an existing user is matched by `appleSub` or by a verified email. properties: givenName: type: string example: Ada familyName: type: string example: Lovelace brandingId: type: string description: >- Same optional branding hint accepted by `/api/auth/autosignup` and `/api/auth/signin` — switches the active institution to the branded twin when the user is already a member. example: pub_6430736fd62d650040420674 SignInResponse: type: object description: | Successful signin response shape. Two variants are returned by the same endpoint depending on whether email MFA is required: • **JWT issued** — `{ token, profile }`. The user is signed in. • **MFA challenge** — `{ mfaRequired: true, challengeId, maskedEmail, mandatorySuper? }`. The client must POST the 6-digit code to `/api/auth/mfa/verify` with the challengeId; the verify endpoint then issues the JWT. Discriminate via `mfaRequired === true` (per Phase 1 design §6.1). properties: token: type: string description: >- Signed JWT token. Present when MFA is not required or has just been verified. Include this in subsequent API requests via the x-access-token header or Authorization Bearer header. Expires after 6 hours (configurable via JWT_VALIDITY_SEC). Automatically refreshed on profile load (sliding session). example: >- eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2NDMwNzM2ZmQ2MmQ2NTAwNDA0MjA2NzQiLCJlbWFpbCI6ImpvaG4uZG9lQG15ZG9tYWluLmNvbSIsImN1c3RvbWVySWQiOiJjdXNfTnh4eHh4eCIsImFjY291bnRUeXBlIjoidXNlciIsInNlc3Npb25JZCI6InMlM0FhYmMxMjMiLCJpYXQiOjE3MDAwMDAwMDAsImV4cCI6MTcwMDA4NjQwMH0.signature profile: $ref: '#/components/schemas/UserProfile' brandingSwitch: $ref: '#/components/schemas/BrandingSwitchVerdict' mfaRequired: type: boolean description: >- When true, the response is an MFA challenge — no JWT issued. Client should redirect to the MFA verify screen with the challengeId. example: true challengeId: type: string description: > MongoDB ObjectId of the issued mfaChallenge. Only present when `mfaRequired: true`. POST this to `/api/auth/mfa/verify` alongside the 6-digit code. example: 6856fa89cbafcff8d98680f5 maskedEmail: type: string description: > Partially-masked email address the verification code was sent to (for the verify-screen "code sent to …" prompt). Only present when `mfaRequired: true`. example: j*****e@example.com mandatorySuper: type: boolean description: | Phase 2 — when `true`, this MFA challenge was issued under super-mandatory enforcement (MFA_SUPER_MANDATORY=true and the user is past the rollout date). The verify screen should render an explanatory banner and suppress the Cancel affordance, since the user can't dismiss the flow without enrolling. On successful verify, the server persists `user.mfaEnabled = true` so the next signin follows the normal phase-1 trusted-device path. Only present when `mfaRequired: true` AND the gate fired. Omitted (not `false`) otherwise — clients should default to `false` when absent. example: true AppleSignInError: type: object required: - success - code - message properties: success: type: boolean enum: - false code: type: string description: > Machine-readable failure reason. Every message is enumeration-safe — it never discloses whether an account with a given email exists. See the endpoint's per-status breakdown below for which codes come back with which HTTP status. enum: - APPLE_TOKEN_INVALID - APPLE_TOKEN_EXPIRED - APPLE_AUDIENCE_MISMATCH - APPLE_NONCE_MISMATCH - APPLE_SIGNIN_FAILED - APPLE_EMAIL_REQUIRED - APPLE_EMAIL_UNVERIFIED - APPLE_ACCOUNT_CONFLICT - APPLE_JWKS_UNAVAILABLE - APPLE_NOT_CONFIGURED message: type: string description: >- User-displayable explanation. Stable per code; safe to show directly. example: >- Apple has not verified the email address on this Apple ID. Verify it with Apple, then try again. UserProfile: type: object properties: _id: type: string email: type: string format: email fname: type: string lname: type: string picture: type: string accountType: type: string permissions: type: array items: type: string customerId: type: string lxp_user_id: type: string lxp_user_type: type: integer lxp_partner_id: type: string lxp_partner_name: type: string lxp_role_id: type: integer lxp_role_name: type: string credits: type: integer creditsUsed: type: integer plan: type: string status: type: string trial_end: type: string format: date-time trial_used: type: boolean current_period_end: type: string format: date-time cancel_at_period_end: type: boolean referralId: type: string format: uuid referrerPaid: type: boolean resetCodeId: type: string format: uuid invoices_urls: type: array items: type: string remember_history_count: type: integer browser_voice: type: string rt_voice: type: string use_location: type: boolean showSideBar: type: boolean dark_mode: type: boolean created: type: string format: date-time __v: type: integer institution: $ref: '#/components/schemas/InstitutionProfile' BrandingSwitchVerdict: type: object description: >- Outcome of a branded-link switch attempt. Present only when the request carried a `brandingId` (an institution publicId from a /login?brandingId= link). The hint never grants access: `switched` requires an active membership on the twin (or platform-operator status) and an active parent account. Clients clear the stored hint on `switched`/`already` and show the no-access notice on `refused`. properties: publicId: type: string description: The institution publicId the request asked for. example: f831501f-b645-481a-9cbb-331509aaf8c1 result: type: string enum: - switched - already - refused - ignored reason: type: string nullable: true description: >- Why the switch was refused or ignored — one of no_hint, unknown_twin, no_membership, institution_inactive, account_inactive, error; null on switched/already. InstitutionProfile: type: object properties: _id: type: string name: type: string picture: type: string picture_bg: type: string picture_dark_bg: type: string picture_animated: type: string elevenlabs_agent_id: type: string credits: type: integer status: type: string allowJoining: type: string joiningAdminOnly: type: boolean publicId: type: string format: uuid publicAuthorizedUrls: type: array items: type: string ainame: type: string contactEmail: type: string format: email creditAward: type: integer poolCredits: type: boolean invoices_urls: type: array items: type: string maxCompletionTokens: type: integer disableFileUploadForUser: type: boolean disableAudioNotesForUser: type: boolean toolsDisabled: type: array items: type: string ltiContextIds: type: array items: type: string personalisationAsked: type: boolean locationEnabled: type: boolean rtEnabled: type: boolean rtAdminOnly: type: boolean displayAgentDetails: type: boolean displayThinkingDetails: type: boolean displayRagSearchDetails: type: boolean displayMemoryDetails: type: boolean displayThinkingExecution: type: boolean displayToolExecution: type: boolean assistantsDisabled: type: array items: type: string disableAssistantsForUser: type: boolean rtVoice: type: string maxFiles: type: integer questionType: type: string creditsTotal: type: integer nullable: true creditsUsagePct: type: number id: type: string ````