# descope-auth

Guides adding Descope login to an app, covering passwordless sign-in, OAuth, SSO and MFA, with steps for each framework.

Skill by Descope. Category: Security.

## Install

Project (for this project only):

```sh
npx skills add descope/skills --skill descope-auth
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add descope/skills --skill descope-auth -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass
- Runlayer: Warn

Installs: 66. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/descope/skills/descope-auth)

## Source

[Open the source](https://github.com/descope/skills/tree/HEAD/skills/descope-auth). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: descope-auth
description: Integrate Descope authentication into applications. Use when implementing login, signup, passwordless auth (OTP, Magic Link, Passkeys), OAuth, SSO, or MFA. Detects framework and provides targeted guidance.
---

# Descope Authentication

Integrate secure, passwordless authentication using Descope Flows and SDKs.

## Framework Detection

Detect the user's framework and use the appropriate reference:

| If project has... | Use reference |
|-------------------|---------------|
| `next` in package.json | `references/nextjs.md` |
| `react` (no Next.js) | `references/react.md` |
| `@angular/core` in package.json | `references/angular.md` |
| No frontend framework (plain HTML/JS) | `references/vanilla-js.md` |
| Python/Node.js backend only | `references/backend.md` |

## Quick Start (all frameworks)

1. Get Project ID from https://app.descope.com/settings/project
2. Set environment variable: `NEXT_PUBLIC_DESCOPE_PROJECT_ID=<your-id>`
3. Follow framework-specific reference
4. **Verify**: After setup, confirm the `<Descope>` component renders the login form. Check the browser console — a missing or invalid Project ID produces a clear `Could not load flows` error.

### Minimal Inline Example (Next.js)

```tsx
// src/app/login/page.tsx
import { Descope } from '@descope/nextjs-sdk';

export default function LoginPage() {
  return (
    <Descope
      flowId="sign-up-or-in"
      onSuccess={(e) => console.log('Authenticated:', e.detail.user)}
      onError={(e) => console.error('Auth failed:', e.detail)}
    />
  );
}
```

For React SPA or backend-only setups, see the framework-specific references below.

## Valid Flow IDs (CRITICAL - do not invent others)

| Flow ID | Purpose |
|---------|---------|
| `sign-up-or-in` | Combined signup/login (RECOMMENDED) |
| `sign-up` | Registration only |
| `sign-in` | Login only |
| `step-up` | MFA step-up authentication |
| `update-user` | Profile updates, add auth methods |

## Authentication Methods

| Method | When to use |
|--------|-------------|
| OTP (Email/SMS) | Quick verification codes |
| Magic Link | Passwordless email links |
| Passkeys | Biometric/WebAuthn (most secure) |
| OAuth | Social login (Google, GitHub, etc.) |
| SSO | Enterprise SAML/OIDC |
| Passwords | Traditional auth (not recommended) |

## DO NOT (Security Guardrails)

- DO NOT parse JWTs manually - always use SDK's `validateSession()`
- DO NOT store tokens in localStorage - SDK handles this securely
- DO NOT invent flow IDs - only use IDs from the table above
- DO NOT skip server-side validation - always validate on backend
- DO NOT expose DESCOPE_MANAGEMENT_KEY in client code

## References

- `references/nextjs.md` - Next.js App Router & Pages Router integration
- `references/react.md` - React SPA integration
- `references/angular.md` - Angular integration
- `references/vanilla-js.md` - Vanilla JavaScript / plain HTML integration
- `references/backend.md` - Backend session validation
````

- Previous: [orchestrate-multi-target-sdks](https://syn4pse.dev/terminal/speakeasy-orchestrate-multi-target-sdks.md)
- Next: [auth-review](https://syn4pse.dev/terminal/descope-auth-review.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
