Vue.js & Django Quickstart

This is a quickstart guide to help you integrate Descope with your Vue.js & Django application. Follow the steps below to get started.

Install Frontend SDK

Install the SDK with the following command:

Terminal

npm i --save @descope/vue-sdk

Add Vue SDK to your Application

Start by importing Descope and add the Vue SDK to your application. You will need your Project ID from Project Settings in the Descope Console.

Note

You can also add the optional baseUrl parameter if you're utilizing a CNAME within your Descope project (ex: https://auth.company.com).

App.vue

import { createApp } from "vue";
import App from "@/App.vue";
import router from "./router";
import descope, { getSdk } from "@descope/vue-sdk";
 
const app = createApp(App);
app.use(router);
 
app.use(descope, {
  projectId: '__ProjectID__',
  baseUrl: "<base url>", // Optional
});
 
const sdk = getSdk();
sdk?.onSessionTokenChange((newSession) => {
  // here you can implement custom logic when the session is changing
});
 
app.mount("#app");

Use the SDK to Render a Specific Flow

In your Vue template, use the <Descope> component to render a specific authentication flow. Customize this component with properties like flowId, @error, @success, and optional attributes for theming, debug mode, and more:

theme: "light" or "dark" mode
tenant: Tenant ID you can pass in for SSO
redirectUrl: Redirect URL for OAuth and SSO (will be used when redirecting back from the OAuth provider / IdP), or for "Magic Link" and "Enchanted Link" (will be used as a link in the message sent to the the user). When configured within the flow, it overrides the configuration within the Descope console.
:errorTransformer: this is a function that receives an error object and returns a string. The returned string will be displayed to the user. errorTransformer is not required. If not provided, the error object will be displayed as is. Learn more about how to use the errorTransformer here.
validateOnBlur: a boolean to configure whether field validation is performed when clicking away from the field (true) or on form submission (false)
form: You can optionally pass flow inputs, such as email addresses, names, etc., from your app's frontend to your flow. The configured form inputs can be used within flow screens, actions, and conditionals prefixed with form.
- Ex: form={{ email: "predefinedname@domain.com", firstName: "test", "customAttribute.test": "aaaa", "myCustomInput": 12 }}
client: You can optionally pass flow inputs from your app's frontend to your flow. The configured client inputs can be used within flow actions and conditionals prefixed with client..
- Ex: client={{ version: "1.2.0" }}

Note

More built in functions can be found on the SDK README. You can refer to the rest of the code in Login.vue as an example of implementation. Also note that, Descope stores the last user information in local storage. If you wish to disable this feature, you can pass storeLastAuthenticatedUser as false to the AuthProvider component. Please note that some features related to the last authenticated user may not function as expected if this behavior is disabled.

<template>
  <div class="wrapper">
    <p v-if="isLoading">Loading...</p>
    <div v-else-if="isAuthenticated">
      <h1>You are authenticated</h1>
    </div>
    <Descope
      v-else
      :flowId="sign-up-or-in" // can be any flow id
      @error="handleError"
      @success="handleSuccess"
      :errorTransformer="errorTransformer"
    />
  </div>
</template>
 
<script setup>
import { Descope, useSession } from "@descope/vue-sdk";
const { isLoading, isAuthenticated } = useSession();
 
const handleError = (e) => {
  console.log("Got error", e);
};
 
const handleSuccess = (e) => {
  console.log("Logged in", e);
};
 
const errorTransformer = (error) => {
  const translationMap = {
    SAMLStartFailed: "Failed to start SAML flow",
  };
  return translationMap[error.type] || error.text;
};
</script>

Getting User Details

To extract details on the user, you can load the user details from e.detail.user. On successful authentication, the information about the user is returned and accessible with e.detail.user.

@success - function that executes when authentication succeeds

Example:

<template>
  <div class="wrapper">
    <p v-if="isLoading">Loading...</p>
    <div v-else-if="isAuthenticated">
      <h1>You are authenticated</h1>
    </div>
    <Descope
      v-else
      :flowId="sign-up-or-in"
      @error="handleError"
      @success="handleSuccess" // <-- Called when authentication is successful
      :errorTransformer="errorTransformer"
    />
  </div>
</template>
 
<script setup>
const handleSuccess = (e) => {
  console.log("Logged in", e);
};
</script>

Alternatively, you can also use the me function which fetches the current authenticated user information.

Utilize the Vue SDK Hooks and Functions

Use the useDescope, useSession, and useUser functions in your components to manage authentication state, user details, and utilities like a logout button.

Home.vue

<template>
	<div v-if="isSessionLoading || isUserLoading">Loading ...</div>
	<div v-else-if="isAuthenticated">
		<div>Hello {{ user?.name }}</div>
		<button @click="logout">Logout</button>
	</div>
	<div v-else>You are not logged in</div>
</template>
 
<script setup>
import { useDescope, useSession, useUser } from '@descope/vue-sdk';
 
const { isAuthenticated, isSessionLoading } = useSession();
const { user, isUserLoading } = useUser();
const { logout } = useDescope();
</script>

Pass Session Token to Server API

Use getSessionToken to retrieve the session token, and pass it in the Authorization header of your API requests for server-side validation.

App.vue

import { getSessionToken } from '@descope/vue-sdk';
 
// example fetch call with http header
export const fetchData = async () => {
	const sessionToken = getSessionToken();
	const res = await fetch('/path/to/server/api', {
		headers: {
			Authorization: `Bearer ${sessionToken}`
		}
	});
	// ... use res
};

At this point, you're done with the frontend. If you would like to also handle Session Management in your backend, keep on reading!

Install Backend SDK

Install the SDK with the following command:

Terminal

pip install django-descope

Import and Setup Backend SDK

You'll need install and setup all of the packages from the SDK. This is done by ensuring django_descope is under INSTALLED_APPS in settings.py.

If you're using a CNAME with your Descope project, make sure to export the Base URL (e.g. export DESCOPE_BASE_URI="https://api.descope.com") when initializing descope_client.

settings.py

INSTALLED_APPS = [
  ...
  'django_descope',
]
DESCOPE_PROJECT_ID=os.getenv("DESCOPE_PROJECT_ID")

Add Descope Middleware

Ensure Descope Middleware is after the AuthenticationMiddleware and SessionMiddleware.

settings.py

MIDDLEWARE = [
  ...
  'django.contrib.sessions.middleware.SessionMiddleware',
  'django.contrib.auth.middleware.AuthenticationMiddleware',
  ...
  'django_descope.middleware.DescopeMiddleware',
]

Configure URLconf

You will then need to include the Descope URLconf in your project urls.py like this.

urls.py

path('auth/', include('django_descope.urls')),

Configure URLconf

The session validation is handled in the Django SDK, through the middleware.

settings.py

INSTALLED_APPS = [
  ...
  'django_descope',
]
MIDDLEWARE = [
  ...
  'django.contrib.sessions.middleware.SessionMiddleware',
  'django.contrib.auth.middleware.AuthenticationMiddleware',
  ...
  'django_descope.middleware.DescopeMiddleware',
]
DESCOPE_PROJECT_ID=os.getenv("DESCOPE_PROJECT_ID")

Congratulations

Now that you've got the authentication down, go focus on building out the rest of your app!

Here is a sample application using the Django SDK.

Checkpoint

Your application is now integrated with Descope. Please test with sign-up or sign-in use case.

Need help?

Customize

Now that you have the end-to-end application working, you can choose to configure and personalize many different areas of Descope, including your brand, style, custom user authentication journeys, etc. We recommend starting with customizing your user-facing screens, such as signup and login.

Customize

Was this helpful?

Checkpoint

On this page