# Quick Start

## Creating the Application

The API requests and the JavaScript SDK require a client ID and for some features a client secret, to obtain those you need to create an application using the [Vulos Identity dashboard](https://identity.vulos.io).

You can do that by clicking on the "New Application" link in the left navigation bar and by filling in some details.

In the "Redirect URLs" field you need to specify the link of the callback URL that we will define later on, for now set it to `http://localhost:8080/callback` or `http://localhost:8080/index.html` if you want to implement the browser application flow.

And you need to add the [`openid`](https://dev.vulos.io/scopes-and-claims#openid) scope, for more detailed information about the scopes, take a look at the [scopes-and-claims](https://dev.vulos.io/identity/scopes-and-claims "mention").

## Install the library

{% hint style="info" %}
If you are familiar with the OpenID Connect protocol, you can also use any other OpenID library in any language that you want.

The issuer URL is: `https://identity.vulos.io`
{% endhint %}

The best way to interact with our API is to use one of our official libraries:

{% tabs %}
{% tab title="Node.js" %}

```bash
npm install @vulos/identity-node-sdk --save
```

{% content-ref url="../reference/identity-javascript-sdk/the-backend-auth-package" %}
[the-backend-auth-package](https://dev.vulos.io/reference/identity-javascript-sdk/the-backend-auth-package)
{% endcontent-ref %}
{% endtab %}

{% tab title="Webpack" %}

```
npm install @vulos/identity-browser-sdk --save  
```

{% content-ref url="../reference/identity-javascript-sdk/the-frontend-auth-package" %}
[the-frontend-auth-package](https://dev.vulos.io/reference/identity-javascript-sdk/the-frontend-auth-package)
{% endcontent-ref %}
{% endtab %}

{% tab title="CDN" %}
Add the following script tag to the HTML where you'll integrate Vulos Identity:

{% code title="index.html" %}

```markup
<script src="https://cdn.vulos.io/latest/identity.min.js"></script>
```

{% endcode %}

{% hint style="warning" %}
[the-frontend-auth-package](https://dev.vulos.io/reference/identity-javascript-sdk/the-frontend-auth-package "mention") is exposed as `VulosIdentity.Auth` and [the-base-package](https://dev.vulos.io/reference/identity-javascript-sdk/the-base-package "mention") is exposed as `VulosIdentity.Base` in the global scope.
{% endhint %}
{% endtab %}
{% endtabs %}

## Setting up the OpenID flow

You need to create an application object that matches the application you just created in the dashboard.

{% tabs %}
{% tab title="Node.js / Webpack" %}
{% code title="index.js" %}

```java
import { Application, User } from "@vulos/identity-base" 
const application = new Application({
    id: "<paste your_client id here>",
    
    // if you made a browser application remove this property
    secret: "<paste your client secret here>",
    
    scope: "openid",
    redirectUrls: ["<your website's callback URL>"]
})
```

{% endcode %}
{% endtab %}

{% tab title="CDN" %}
{% code title="index.js" %}

```javascript
const { Application, User } = VulosIdentity.Base
const application = new Application({
    id: "<paste your_client id here>",
    
    // if you made a browser application remove this property
    secret: "<paste your client secret here>",
    
    scope: "openid",
    redirectUrls: ["<your website's callback URL>"]
})
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Node.js" %}
{% code title="index.js" %}

```javascript
import { BackendAuth } from "@vulos/identity-node-sdk"

const auth = application.createAuth(BackendAuth)
await auth.connect()
```

{% endcode %}

Then you need to create a route for the callback URL (in this example we are going to assume that you use `express`) and a route that redirects the user to the login / consent screen:

{% code title="index.js" %}

```javascript
import express from "express"
const app = express()

// it is recommended that you generate a verifier per auth
// request and that you store this in a database or cache
// instead of storing it in a global variable
const verifier = auth.createVerifier()

app.get("/callback", async (req, res) => {
    const user = await auth.processCallback(verifier, req.)
    // you probably want to store this in a database instead
    return res.redirect("/action?tokens=" + JSON.stringify(user.save()))
})

app.get("/login", async (req, res) => {
    // you can also render this is a button instead of a redirect
    return res.redirect(await auth.createAuthUrl(verifier))
})

// this is an example endpoint that uses the api
// it will return a JSON response with the id of the user
app.get("/action", async (req, res) => {
    const user = new User(auth, JSON.parse(req.query['tokens']))
    const userInfo = await user.info()
    return res.json(userInfo.id())
})
```

{% endcode %}
{% endtab %}

{% tab title="Webpack" %}
{% code title="index.js" %}

```javascript
import { FrontendAuth } from "@vulos/identity-browser-sdk"

const auth = application.createAuth(FrontendAuth)
```

{% endcode %}

Then you can create some code that uses local storage for state that authenticates the user and processes the callback parameters:

{% code title="index.js" %}

```javascript
// a function that creates and stores the verifier in local storage
function createAndStoreVerifier() {
    const verifier = auth.createVerifier()
    localStorage.setItem('verifier', JSON.stringify(verifier))
    return verifier
}

// a function that loads and removes the verifier from local storage
function loadAndRemoveVerifier() {
    const json = localStorage.getItem('verifier')
    localStorage.removeItem('verifier')
    return JSON.parse(json) 
        // this part is here to obtain the
        // silent token refresh verifier
        || auth.createVerifier()
} 

// save the user to local storage
function saveUser(user) {
    localStorage.setItem('tokens', JSON.stringify(user.save()))
}

// a function that creates a user object from the saved tokens
function getUser() {
    const tokens = localStorage.getItem('tokens')
    return tokens && new User(auth, JSON.parse(tokens))
}

(async() => {
    await auth.connect()
    let user
    
    if (window.location.hash) {
        // there are parameters in the hash,
        // it's probably a callback request
        try {
            user = await auth.processCallback(
                loadAndRemoveVerifier(),
                 window.location.hash)
            saveUser(user)
        } catch {
            // we don't need to proceed, it's probably
            // a silent token refresh request if this fails
            return
        }
    }
    
    
    user = getUser()

     // the user isn't authenticated
    if (!user) {
        // redirect the user to the login / consent screen
        // you can also render this as a button
        document.location = await auth.createAuthUrl(createAndStoreVerifier())
    }
    
    // find an element with an id of: 'user-id'
    const userIdEl = document.getElementById('user-id')

    // get the id and set the 'user-id' element's text to the id
    const userInfo = await user.info()
    userIdEl.innerText = userInfo.id().toString()
})()
```

{% endcode %}

The `index.html` file for this example should contain the code:

{% code title="index.html" %}

```markup
<p>The user id is: <strong id="user-id"></strong></p>
<script src="index.js"></script>
```

{% endcode %}
{% endtab %}

{% tab title="CDN" %}
{% code title="index.js" %}

```javascript
const { FrontendAuth } = VulosIdentity.Auth

const auth = application.createAuth(FrontendAuth)
```

{% endcode %}

Then you can create some code that uses local storage for state that authenticates the user and processes the callback parameters:

{% code title="index.js" %}

```javascript
// a function that creates and stores the verifier in local storage
function createAndStoreVerifier() {
    const verifier = auth.createVerifier()
    localStorage.setItem('verifier', JSON.stringify(verifier))
    return verifier
}

// a function that loads and removes the verifier from local storage
function loadAndRemoveVerifier() {
    const json = localStorage.getItem('verifier')
    localStorage.removeItem('verifier')
    return JSON.parse(json) 
        // this part is here to obtain the
        // silent token refresh verifier
        || auth.createVerifier()
} 

// save the user to local storage
function saveUser(user) {
    localStorage.setItem('tokens', JSON.stringify(user.save()))
}

// a function that creates a user object from the saved tokens
function getUser() {
    const tokens = localStorage.getItem('tokens')
    return tokens && new User(auth, JSON.parse(tokens))
}

(async() => {
    await auth.connect()
    let user
    
    if (window.location.hash) {
        // there are parameters in the hash,
        // it's probably a callback request
        try {
            user = await auth.processCallback(
                loadAndRemoveVerifier(),
                 window.location.hash)
            saveUser(user)
        } catch {
            // we don't need to proceed, it's probably
            // a silent token refresh request if this fails
            return
        }
    }
    
    
    user = getUser()

     // the user isn't authenticated
    if (!user) {
        // redirect the user to the login / consent screen
        // you can also render this as a button
        document.location = await auth.createAuthUrl(createAndStoreVerifier())
    }
    
    // find an element with an id of: 'user-id'
    const userIdEl = document.getElementById('user-id')

    // get the id and set the 'user-id' element's text to the id
    const userInfo = await user.info()
    userIdEl.innerText = userInfo.id().toString()
})()
```

{% endcode %}

Then you can add the following code to `index.html`:

{% code title="index.html" %}

```markup
<p>The user id is: <strong id="user-id"></strong></p>
<script src="index.js"></script>
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Further reading

After you have a basic app up and running, you can add functionality based on your requirements by adding more scopes and accessing more of the API.

For information about some concepts used in Vulos Identity we suggest reading:

{% content-ref url="organizations" %}
[organizations](https://dev.vulos.io/identity/organizations)
{% endcontent-ref %}

{% content-ref url="scopes-and-claims" %}
[scopes-and-claims](https://dev.vulos.io/identity/scopes-and-claims)
{% endcontent-ref %}

For documentation about the JavaScript SDK we suggest reading:

{% content-ref url="../reference/identity-javascript-sdk" %}
[identity-javascript-sdk](https://dev.vulos.io/reference/identity-javascript-sdk)
{% endcontent-ref %}