# Welcome to the Vulos Identity Documentation!
Here you'll find all the documentation you need to setup an application that uses Vulos Identity.
Quick Start
Do you want to try out the API before reading the detailed documentation?
Have a look at the quick start page:
{% content-ref url="/pages/YhepSQ7LRrJWligxf6OA" %}
[Quick Start](/identity/quick-start)
{% endcontent-ref %}
## Detailed Documentation
On the following pages you can see what's currently possible with the Vulos Identity APIs:
{% content-ref url="/pages/wTOM9GFsbhTTPtFog0ZY" %}
[Organizations](/identity/organizations)
{% endcontent-ref %}
{% content-ref url="/pages/uHiJ9iDVrGSx44VlVmei" %}
[Scopes and Claims](/identity/scopes-and-claims)
{% endcontent-ref %}
{% content-ref url="/pages/dFOhMPNokU0bGlUWsDxS" %}
[Identity JavaScript SDK](/reference/identity-javascript-sdk)
{% endcontent-ref %}
{% content-ref url="/pages/LaVvPyCra6Uov4ozorzv" %}
[Organization API](/reference/organization-api)
{% endcontent-ref %}
{% content-ref url="/pages/EEtaLAJa46SQt0yYirpD" %}
[Profile API](/reference/profile-api)
{% endcontent-ref %}
# 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`](/identity/scopes-and-claims#openid) scope, for more detailed information about the scopes, take a look at the [Scopes and Claims](/identity/scopes-and-claims).
## 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="/pages/TYuDZJHSwcTgtMle63i8" %}
[The Backend Auth Package](/reference/identity-javascript-sdk/the-backend-auth-package)
{% endcontent-ref %}
{% endtab %}
{% tab title="Webpack" %}
```
npm install @vulos/identity-browser-sdk --save
```
{% content-ref url="/pages/HuTVa91ji8rA01ucb83Q" %}
[The Frontend Auth Package](/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
```
{% endcode %}
{% hint style="warning" %}
[The Frontend Auth Package](/reference/identity-javascript-sdk/the-frontend-auth-package) is exposed as `VulosIdentity.Auth` and [The Base Package](/reference/identity-javascript-sdk/the-base-package) 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: "",
// if you made a browser application remove this property
secret: "",
scope: "openid",
redirectUrls: [""]
})
```
{% endcode %}
{% endtab %}
{% tab title="CDN" %}
{% code title="index.js" %}
```javascript
const { Application, User } = VulosIdentity.Base
const application = new Application({
id: "",
// if you made a browser application remove this property
secret: "",
scope: "openid",
redirectUrls: [""]
})
```
{% 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
The user id is:
```
{% 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
The user id is:
```
{% 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="/pages/wTOM9GFsbhTTPtFog0ZY" %}
[Organizations](/identity/organizations)
{% endcontent-ref %}
{% content-ref url="/pages/uHiJ9iDVrGSx44VlVmei" %}
[Scopes and Claims](/identity/scopes-and-claims)
{% endcontent-ref %}
For documentation about the JavaScript SDK we suggest reading:
{% content-ref url="/pages/dFOhMPNokU0bGlUWsDxS" %}
[Identity JavaScript SDK](/reference/identity-javascript-sdk)
{% endcontent-ref %}
# Organizations
This page describes how organizations are structured.
Organizations are entities that contain memberships and that can be associated with applications.
You are able to use organizations for multiple purposes:
* To restrict access over a certain resource/page;
* To manage/keep track a group of users using roles (for example like in an internal company application);
* And more!
A user's relation to an organization is called a **Membership**.
A membership can contain several **roles**, which can be arbitrary strings that are used to describe the purpose of the user in the organization.
There are also some special roles that give the user access to some features.
### Special Roles
Special roles have permissions and a permission level.
The permission level of a role is used to calculate the permission level of the membership, the role with the lowest permission level is counted as main role.
Users cannot preform actions on other users with lower or equal membership permission level.
| Name | Permissions | Permission Level |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `SuperAdmin` |
The ability to associate this organization with an application.
| 3 |
# Scopes and Claims
Here you can see all the scopes and claims we support.
Scopes are permissions that give access to certain claims or APIs, the user can give access to other applications using those scopes. They can be configured using the Vulos Identity dashboard.
Claims can be accessed using the OpenID Connect `userinfo` endpoint or by using [`User.info()`](/reference/identity-javascript-sdk/the-base-package/authentication/user#async-info) in the [JavaScript SDK](/reference/identity-javascript-sdk).
{% hint style="info" %}
See [`UserInfo`](/reference/identity-javascript-sdk/the-base-package/authentication/userinfo) for more information.
{% endhint %}
## User Info
`GET` `https://identity.vulos.io/connect/userinfo`
Use an access token to get claims appropriate to the scopes of the application that created the access token.
#### Headers
| Name | Type | Description |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------- |
| Authorization\* | String | Bearer authentication with the access token obtained using OpenID Connect |
{% tabs %}
{% tab title="200: OK An object that contains claims" %}
```javascript
{ "sub": "", ... }
```
{% endtab %}
{% endtabs %}
### `openid`
This scope can be used to identify the user using the `sub` claim, which is a per-user unique identifier.
{% hint style="warning" %}
This is a required scope, meaning that if the user decides do use an app, they cannot restrict access to this scope if the app requires it.
{% endhint %}
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// assuming you have done the correct setup and have an UserInfo instance
const userId = userInfo.sub() // there is an alias called id() as well
```
{% endtab %}
{% tab title="JSON" %}
```json
{
"sub": ""
}
```
{% endtab %}
{% endtabs %}
### `email`
This scope can be used to get the user's email and their email confirmation status.
{% hint style="warning" %}
This is a required scope, meaning that if the user decides do use an app, they cannot restrict access to this scope if the app requires it.
{% endhint %}
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// assuming you have done the correct setup and have an UserInfo instance
if (userInfo.isEmailVerified()) {
const email = userInfo.email()
// do something with the email
}
```
{% endtab %}
{% tab title="JSON" %}
```json
{
"email": "john.doe@example.com",
"email_veerified": false
}
```
{% endtab %}
{% endtabs %}
### `profile`
This scope can be used to get some personal information about the user.
{% hint style="warning" %}
This is a required scope, meaning that if the user decides do use an app, they cannot restrict access to this scope if the app requires it.
{% endhint %}
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// assuming you have done the correct setup and have an UserInfo instance
const profilePicture = userInfo.picture()
const firstName = userInfo.firstName()
const lastName = userInfo.lastName()
const birthDate = userInfo.birthDate()
```
{% endtab %}
{% tab title="JSON" %}
```json
{
"picture": "",
"given_name": "John",
"family_name": "Doe",
"birthdate": "YYYY-MM-DD"
}
```
{% endtab %}
{% endtabs %}
### `profile:read`
Provides access to the [Profile API](/reference/profile-api).
### `address`
This scope can be used to get the user's address.
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// assuming you have done the correct setup and have an UserInfo instance
const address = userInfo.address()
```
{% endtab %}
{% tab title="JSON" %}
```json
{
"address": "{ ... }"
}
```
{% endtab %}
{% endtabs %}
### `public`
This scope can be used to get the user's trust level and KYC verification status.
{% hint style="warning" %}
This is a required scope, meaning that if the user decides do use an app, they cannot restrict access to this scope if the app requires it.
{% endhint %}
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// assuming you have done the correct setup and have an UserInfo instance
if (userInfo.isKycVerified()) {
// the user has done a successful KYC verification
}
if (userInfo.trustLevel() >= 2) {
// the user has a high trust level
}
```
{% endtab %}
{% tab title="JSON" %}
```json
{
"trust_level": 1,
"kyc_verified": false
}
```
{% endtab %}
{% endtabs %}
### `private`
This scope can be used to get the user's digital ID and national ID.
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// assuming you have done the correct setup and have an UserInfo instance
const nationalId = userInfo.nationalId()
```
{% endtab %}
{% tab title="JSON" %}
```json
{
"national_id": "",
"digital_id": ""
}
```
{% endtab %}
{% endtabs %}
### `wallet`
This scope can be used to get the user's Ethereum and Velas wallet addresses.
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// assuming you have done the correct setup and have an UserInfo instance
const wallets = userInfo.wallets()
for (const walletAddress of wallets) {
// do something with the user's wallet address
}
```
{% endtab %}
{% tab title="JSON" %}
```json
{
"wallet_address": [
"",
""
]
}
// ... or
{
"wallet_address": ""
}
```
{% endtab %}
{% endtabs %}
### `organization`
The organization scope group is divided in 3 scopes:
* `organization:read` which provides the claims `organization:name` and `organization:id` for all the organizations that the user has a membership for;
* `organization:roles` which provides the `organization:role` claim for the roles that the user has in the application's associated organization;
* `organization:manage` which provides access to the [Organization API](/reference/organization-api);
#### `organization:read`
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// assuming you have done the correct setup and have an UserInfo instance
if (userInfo.isInOrganizationWithName("Example Organization")) {
// the user is in the organization "Example Organization"
}
if (userInfo.isInOrganizationWithId(5)) {
// the user is in the organization that has the id 5
}
```
{% endtab %}
{% tab title="JSON" %}
```json
{
"organization:id": [2, 5]
"organization:name": ["Test Organization", "Example Organization"]
}
// ... or
{
"organization:id": 5
"organization:name": "Example Organization"
}
```
{% endtab %}
{% endtabs %}
#### `organization:roles`
{% hint style="warning" %}
This is a required scope, meaning that if the user decides do use an app, they cannot restrict access to this scope if the app requires it.
{% endhint %}
{% tabs %}
{% tab title="JavaScript" %}
```javascript
// assuming you have done the correct setup and have an UserInfo instance
if (userInfo.hasRole("SuperAdmin")) {
// the user has the SuperAdmin role in the app's associated organization
}
```
{% endtab %}
{% tab title="JSON" %}
```json
{
"organization:role": ["SuperAdmin", "Example"]
}
// .. or
{
"organization:role": "SuperAdmin"
}
```
{% endtab %}
{% endtabs %}
#### `organization:manage`
This scope doesn't provide any claims, it just provides access to the following API:
{% content-ref url="/pages/LaVvPyCra6Uov4ozorzv" %}
[Organization API](/reference/organization-api)
{% endcontent-ref %}
### `kyc`
The `kyc` scope group is divided in 2 scopes:
* `kyc:read` which gives access to the KYC status and list APIs;
* `kyc:write` which gives access to the KYC create and upload APIs;
{% content-ref url="/pages/LkDwL4u1SumoKyeR6ErH" %}
[KYC API](/reference/kyc-api)
{% endcontent-ref %}
### `event`
The event scope group is divided in 3 scopes:
* `event:create` which lets the application create event sessions;
* `event:read` which lets the application read/subscribe to event sessions;
* `event:write` which lets the application push events to a session;
# Identity JavaScript SDK
{% content-ref url="/pages/1o9wAVGnNFH9vBQrURhL" %}
[The Base Package](/reference/identity-javascript-sdk/the-base-package)
{% endcontent-ref %}
{% content-ref url="/pages/TYuDZJHSwcTgtMle63i8" %}
[The Backend Auth Package](/reference/identity-javascript-sdk/the-backend-auth-package)
{% endcontent-ref %}
{% content-ref url="/pages/HuTVa91ji8rA01ucb83Q" %}
[The Frontend Auth Package](/reference/identity-javascript-sdk/the-frontend-auth-package)
{% endcontent-ref %}
# The Base Package
This package contains the common logic and interfaces for all JavaScript implementations of the SDK.
`npm install @vulos/identity-base --save`
## Classes
{% content-ref url="/pages/wkGqWDzDWboA8IZpaILr" %}
[Cache](/reference/identity-javascript-sdk/the-base-package/cache)
{% endcontent-ref %}
## Groups
{% content-ref url="/pages/SLSwLJK2e7oPmHjSYBVA" %}
[Authentication](/reference/identity-javascript-sdk/the-base-package/authentication)
{% endcontent-ref %}
{% content-ref url="/pages/a1PIJykbnI5vRPxPgDyG" %}
[Organizations](/reference/identity-javascript-sdk/the-base-package/organizations)
{% endcontent-ref %}
# KYC
## Classes
{% content-ref url="/pages/ZqcMcAkkmsRD3G1Rl48H" %}
[KycStatus](/reference/identity-javascript-sdk/the-base-package/kyc/kycstatus)
{% endcontent-ref %}
{% content-ref url="/pages/4iuJNBUZVNLkyQw1TtzV" %}
[KycInstance](/reference/identity-javascript-sdk/the-base-package/kyc/kycinstance)
{% endcontent-ref %}
{% content-ref url="/pages/QsU5phpRMceg9zyvBKbe" %}
[KycDetails](/reference/identity-javascript-sdk/the-base-package/kyc/kycdetails)
{% endcontent-ref %}
{% content-ref url="/pages/XWcxSguE5hiFb5k57Cj0" %}
[KycApi](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi)
{% endcontent-ref %}
# KycStatus
## Members
### `api :` [`KycApi`](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi)
The `KycApi` instance that this object was created with.
### `status :` [`KycStatusResponse`](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi#kycstatusresponse)
An object that implements the `KycStatusResponse` interface.
## Methods
### `constructor(api, status)`
Create a new instance of the `KycStatus` object.
* `api` must be an instance of [`KycApi`](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi);
* `status` must be an object that implements the [`KycStatusResponse`](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi#kycstatusresponse) interface;
{% hint style="warning" %}
This constructor should not be called directly, use [`KycInstance.status()`](/reference/identity-javascript-sdk/the-base-package/kyc/kycinstance#async-status)instead.
{% endhint %}
### `id()`
Get the id of the request.
This function returns a `string`.
```javascript
const id = kycStatus.id()
```
### `isComplete()`
Is the KYC verification complete?
This function returns a `boolean`.
```javascript
if (kycStatus.isComplete()) {
// do something
}
```
### `isSuccessful()`
Was the KYC verification successful?
This function returns a `boolean`.
```javascript
if (kycStatus.isSuccessful()) {
// do something
}
```
### `distance()`
Get the machine learning algorithm distance.
This function returns a `number` between `0` and `1`.
```javascript
if (kycStatus.distance() > 0.9) {
// the user sent something worse than random noise
}
```
### `createdAt()`
When was the KYC verification requested?
This function returns a `Date` object.
```javascript
const createdDate = kycStatus.createdAt()
```
### `completedAt()`
When was the KYC verification completed?
This function returns a `Date` object.
```javascript
const completedDate = kycStatus.completedAt()
```
### `webhook()`
Get the webhook URL that got / will get called when the request is complete.
This function returns an `URL` object.
```javascript
const webhookUrl = kycStatus.webhook()
```
# KycInstance
## Members
### `api :` [`KycApi`](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi)
The `KycApi` instance that this object was created with.
### `id : string`
The ID of this KYC instance.
## Methods
### `constructor(api, id)`
Create a new instance of the `KycInstance` object.
* `api` must be an instance of [`KycApi`](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi);
* `id` must be the ID of a KYC Instance;
{% hint style="warning" %}
This constructor should not be called directly, use `ApplicationReference.createKycRequest()` or `ApplicationReference.listKycRequests()` instead.
{% endhint %}
### `async status()`
Get the status of this KYC instance.
This function returns a [`KycStatus`](/reference/identity-javascript-sdk/the-base-package/kyc/kycstatus) object.
```javascript
const kycStatus = await kycInstance.status()
```
# KycDetails
## Members
### `api :` [`KycApi`](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi)
The `KycApi` that this object was created with.
### `details :` [`KycDetailsResponse`](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi#kycdetailsresponse)
An object that implements the `KycDetailsResponse` interface.
## Methods
### `constructor(api, details)`
Create a new instance of the `KycDetails` object.
* `api` must be an instance of [`KycApi`](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi);
* `details` must implement the [`KycDetailsResponse`](/reference/identity-javascript-sdk/the-base-package/kyc/kycapi#kycdetailsresponse) interface;
{% hint style="warning" %}
This constructor should not be called directly, use `ApplicationReference.uploadKycDetails()` instead.
{% endhint %}
### `async createRequest(webhook)`
Create a new KYC request based on the details, the `webhook` argument is optional.
This function returns a [`KycInstance`](/reference/identity-javascript-sdk/the-base-package/kyc/kycinstance).
```javascript
const kycInstance = await kycDetails.createRequest()
```
# KycApi
{% hint style="info" %}
This class implements [`BasicApi`](broken://pages/xlI4X77sh7TTM0rFdmRn).
{% endhint %}
{% hint style="warning" %}
You need [`kyc:read`](/identity/scopes-and-claims#kyc) or [`kyc:write`](/identity/scopes-and-claims#kyc) to access some parts of this API.
{% endhint %}
{% hint style="info" %}
This is a JavaScript implementation of the [KYC API](/reference/kyc-api).
{% endhint %}
{% hint style="info" %}
For ease of use we recommend using the [`ApplicationReference`](broken://pages/EPAyUPEf3e2NaRcAMaM0) object for interaction instead.
{% endhint %}
## Interfaces
### `KycStatusResponse`
```typescript
interface KycStatusResponse {
complete: boolean,
success: boolean,
distance: number,
createdAt: string,
completedAt: string,
webhook: string|null
}
```
### `KycDetailsResponse`
```typescript
interface KycDetailsResponse {
idCardPictureUrl: string,
selfiePictureUrl: string
}
```
## Methods
### `constructor(app, endpoint)`
Create a KYC API object.
* `app` should be an instance of the [`ApplicationReference`](broken://pages/EPAyUPEf3e2NaRcAMaM0) object.
* `endpoint` should be the Vulos Identity endpoint.
```javascript
const kycApi = new KycApi(appRef, endpoint)
```
### `async status(kycId)`
Get the status of a KYC verification instance by ID.
The result implements the [`KycStatusResponse`](#undefined) interface.
{% hint style="info" %}
This method's response has the `kyc:status` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const status = await kycApi.status(kycId)
```
### `async list(page, pageSize)`
Get a list of all the KYC verification instance IDs.
* `page` defaults to 0;
* `pageSize` defaults to 10;
The result is an array of KYC Instance IDs.
{% hint style="info" %}
This method's response has the `kyc:list` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const first10 = await kycApi.list()
```
### `async upload(selfiePicture, idCardPicture)`
Upload KYC verification details for later use, both of the arguments must be objects that inherit from `Blob` (like `File`).
The result implements the [`KycDetailsResponse`](#undefined) interface.
```javascript
const details = await kycApi.upload(selfieFile, idCardFile);
```
### `async create(selfiePicture, idCardPicture, webhook)`
Make a KYC verification request, the first two arguments may be objects that inherit from `Blob` or URLs returned by the [`upload()`](#async-upload-selfiepicture-idcardpicture) method, the `webhook` argument is optional.
The result is the ID of the KYC Instance that was created.
{% hint style="warning" %}
The webhook must be in the application's redirect URLs otherwise the server will return the "Bad Request" response.
{% endhint %}
```javascript
const kycId = await kycApi.create(selfieFile, idCardFile, 'http://example.com/webhook');
```
# Profile
## Classes
{% content-ref url="/pages/MYeYnnNVt3pWJAfh71pX" %}
[ProfileApi](/reference/identity-javascript-sdk/the-base-package/profile/profileapi)
{% endcontent-ref %}
{% content-ref url="/pages/D9I4I4CbTjJxSaswb7Ej" %}
[UserReference](/reference/identity-javascript-sdk/the-base-package/profile/userreference)
{% endcontent-ref %}
# UserReference
## Members
### `id : string`
The ID of the user that this object references.
### `profileApi :` [`ProfileApi`](/reference/identity-javascript-sdk/the-base-package/profile/profileapi)
The Profile API instance that can be used for interaction.
## Methods
### `constructor(id, profileApi)`
Create an instance of this class.
* `id` must be a user ID.
* `profileApi` must be an instance of [`ProfileApi`](/reference/identity-javascript-sdk/the-base-package/profile/profileapi).
### `async profile()`
Get this user's public profile.
This function returns an object that implements the [`ProfileInfo`](/reference/identity-javascript-sdk/the-base-package/profile/profileapi#profileinfo) interface.
```javascript
const profile = await userRef.profile()
```
# ProfileApi
{% hint style="info" %}
This class implements [`BaseApi`](/reference/identity-javascript-sdk/the-base-package/authentication/baseapi).
{% endhint %}
{% hint style="warning" %}
You need the [`profile:read`](/identity/scopes-and-claims#profile-read) scope to access this API.
{% endhint %}
{% hint style="info" %}
This is a JavaScript implementation of the [Profile API](/reference/profile-api).
{% endhint %}
{% hint style="info" %}
For ease of use we recommend using the [`User`](/reference/identity-javascript-sdk/the-base-package/authentication/user) object for interaction instead.
{% endhint %}
## Interfaces
### `OrganizationProfileInfoWithId`
```typescript
interface OrganizationProfileInfoWithId implements OrganizationProfileInfo {
id: number
}
```
### `OrganizationProfileInfo`
```typescript
interface OrganizationProfileInfo {
name: string,
address?: string,
city?: string,
country?: string,
state?: string,
website?: string,
verified?: boolean,
uniqueId?: string,
zipCode?: string
}
```
### `ProfileInfo`
```javascript
interface ProfileInfo {
firstName?: string,
lastName?: string,
country?: {
alpha2: string,
name: string
},
email?: {
value: string,
confirmed: boolean
},
kycVerified?: boolean,
state?: string,
profilePicture?: string
}
```
## Methods
### `constructor(user, endpoint)`
Create a Profile API object.
* `user` should be an instance of the [`User`](/reference/identity-javascript-sdk/the-base-package/authentication/user) object.
* `endpoint` should be the Vulos Identity endpoint.
```javascript
const profileApi = new ProfileApi(user, endpoint)
```
### `async info(id)`
Get an user's public profile by the user's ID.
The result implements the [`ProfileInfo`](#undefined) interface.
{% hint style="info" %}
This method's response has the `profile:info` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const userProfile = await profileApi.info(userId)
```
### `async organization(id)`
Get an organization's public profile by the organization's ID.
The result implements the [`OrganizationProfileInfo`](#organizationinfo) interface.
{% hint style="info" %}
This method's response has the `profile:organization` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const organizationProfile = await profileApi.organization(organizationId)
```
### `async organizationSearch(search, amount, offset)`
Search for an organization by name using a string.
* `search` is the string we are searching with in the organization's name;
* `amount` is the maximal amount of elements that can be returned (absolute maximal is `100`, default is `10`), this argument is optional;
* `offset` is the amount of organizations that will get skipped in the result (default is `0`), this argument is optional;
The result implements the [`OrganizationProfileInfoWithId`](#organizationprofileinfowithid) interface.
{% hint style="info" %}
This method's response has the `profile:organization:search` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const [bestMatch] = await profileApi.organizationSearch('Example')
// ... or
let pageIndex = 0
const organizationsPerPage = 5
const nextPage = async () => {
const organizations = await profileApi.organizationSearch(
'Example',
organizationsPerPage,
organizationsPerPage * pageIndex)
pageIndex++
return organizations
}
let currentPage
while(currentPage = await nextPage()) {
// do something with the current page
}
```
# Cache
## Members
### `policy : Map`
The cache policies that this application uses.
### `storage : any`
Any object that can be used as storage, valid values can be `{}`, `window.localStorage`, `window.sessionStorage` or any class that can be used as a key/value storage.
## Methods
### `constructor(storage)`
Create a cache instance that can be used in the SDK.
* `storage` should match the [`storage`](#storage-any) member;
```javascript
const myCache = new Cache(window.localStorage)
```
### `async cache(key, callback)`
Attempt to get a cached value based on a key, it is not found in the cache, create it from the callback function.
{% hint style="info" %}
The callback function can be asynchronous.
{% endhint %}
```javascript
const value = await myCache.cache('key', () => 'value')
```
### `invalidate(key)`
Remove a key or a cache group from the cache.
* `key` must be a string that matches the cache key or a regular expression;
```javascript
myCache.invalidate('key')
// ... or
myCache.invalidate(/^key/)
```
### `addPolicy(key, lifespan)`
Add a new cache policy to the cache object.
* `key` must be a string that matches the cache key or a regular expression;
* `lifespan` specifies for how long the cache object should be valid in seconds;
```javascript
myCache.addPolicy('key', 300) // keep the object for 5 minutes
// ... or
myCache.addPolicy(/^key/, 300) // the same length as above but as a regex
```
### `static use(cacheBuilder)`
Use a specific cache object for the global cache.
* `cacheBuilder` must be a function that returns `Cache`;
```javascript
Cache.use(() => myCache)
// ... or
Cache.use(() => new Cache(window.sessionStorage)
.addPolicy(/^key/, 300)
.addPolicy('other', 5))
```
### `static get()`
Get the global cache object.
```javascript
const globalCache = Cache.get()
```
## Helpers
### `async function cache(key, callback)`
Cache something globally.
{% hint style="info" %}
This function is an alias for [`Cache.get().cache(key, callback)`](#async-cache-key-callback).
{% endhint %}
```javascript
const value = await cache('key', () => 'value')
```
### `function invalidate(key)`
Invalidate something from global cache.
{% hint style="info" %}
This function is an alias for [`Cache.get().invalidate(key)`](#invalidate-key).
{% endhint %}
### `escapePolicyPart(string)`
Escape a variable to be used in a regex.
```javascript
const value = '/-/' // this cannot be used in a regex without modifying it
const escapedValue = escapePoliciyPart(value)
```
# Authentication
## Classes
{% content-ref url="/pages/Tn5x4BWmmYEHpeQ2kh7T" %}
[Application](/reference/identity-javascript-sdk/the-base-package/authentication/application)
{% endcontent-ref %}
{% content-ref url="/pages/scytutZ8Sn0vqSb17YOx" %}
[BaseAuth](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth)
{% endcontent-ref %}
{% content-ref url="/pages/RB4bYSpMdLvmOIBu2xCG" %}
[User](/reference/identity-javascript-sdk/the-base-package/authentication/user)
{% endcontent-ref %}
{% content-ref url="/pages/oqPm5q66sEQAH8mVQw6k" %}
[UserInfo](/reference/identity-javascript-sdk/the-base-package/authentication/userinfo)
{% endcontent-ref %}
{% content-ref url="/pages/By3Rwa7BymzNTUPLID18" %}
[BaseApi](/reference/identity-javascript-sdk/the-base-package/authentication/baseapi)
{% endcontent-ref %}
{% content-ref url="/pages/xlI4X77sh7TTM0rFdmRn" %}
[Broken mention](broken://pages/xlI4X77sh7TTM0rFdmRn)
{% endcontent-ref %}
{% content-ref url="/pages/EPAyUPEf3e2NaRcAMaM0" %}
[Broken mention](broken://pages/EPAyUPEf3e2NaRcAMaM0)
{% endcontent-ref %}
# Application
## Members
### `id : string`
The Client ID of this application.
### `secret : string?`
The Client Secret of this application.
### `scope : string`
The [OpenID scope](/identity/scopes-and-claims) of this application.
### `responseTypes : string[]`
The OpenID response types of this application.
### `redirectUrls : string[]`
The OpenID redirect URLs of this application.
### `postLogoutRedirectUrls : string[]?`
The OpenID post logout redirect URLs of this application.
## Methods
### `constructor(config)`
Create a Vulos Application object based on a configuration object that has the following properties:
* `id: string` (required): The Client ID of the Application (you can obtain this from the Vulos Identity dashboard by creating an application);
* `secret: string`: The Client Secret of the Application (you can obtain this from the Vulos Identity dashboard by creating an application, non-applicable for browser applications that use the implicit flow);
* `scope: string` (required): The OIDC scopes - "permissions" that your application has, they must match your application in the Vulos Identity dashboard.
* `redirectUrls: string[]` (required): The URLs where Vulos Identity redirects after a user interaction;
* `postLogoutRedirectUrls: string[]`: The URLs where Vulos Identity redirects after a successful logout;
* `responseTypes: string[]`: The OIDC response types (defaults to `['code']` if a client secret is provided);
```javascript
const application = new Application({
// this is an example Client ID, replace with your own
id: "796FZE9KLOLO0VSSBNOE",
// this is an example Client Secret, replace with your own
secret: "5a9b30a4f2f7f5edb5087e2258c3ecc0fc4129853e28f2f48f10b21b60388f1f",
// this is an example scope string, modify according to your needs
scope: "openid offline_access organization:manage",
// change these URLs to match your site or application
redirectUrls: [ "http://localhost/callback/login" ],
postLogoutRedirectUrls: [ "http://localhost/callback/logout" ],
// https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html
responseTypes: [ "code" ]
})
```
### `createAuth(authApi, endpoint?)`
Create an authentication object for this application based on a constructor specified in `authApi` that's provided by [`@vulos/identity-browser-sdk`](/reference/identity-javascript-sdk/the-frontend-auth-package) or [`@vulos/identity-node-sdk`](/reference/identity-javascript-sdk/the-backend-auth-package).
{% hint style="info" %}
If an `endpoint` argument is provided, that will be used instead of the default Vulos Identity endpoint.
{% endhint %}
```javascript
// If you intend to use this code in the frontend,
// use "FrontendAuth" from "@vulos/identity-browser-sdk"
import { BackendAuth } from "@vulos/identity-node-sdk"
// ...
const auth = application.createAuth(BackendAuth)
```
{% hint style="info" %}
See [`BaseAuth`](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth) for more information.
{% endhint %}
# BaseAuth
{% hint style="warning" %}
This class is an interface, it shouldn't be created directly.
{% endhint %}
## Members
### `application :` [`Application`](/reference/identity-javascript-sdk/the-base-package/authentication/application)
The application that this object is associated with.
### `endpoint : string`
The Vulos Identity server endpoint URL.
## Methods
### `constructor(application, endpoint?)`
This should only get called by classes that inherit the `BaseAuth` class.
* `application` should be an instance of the [`Application`](/reference/identity-javascript-sdk/the-base-package/authentication/application) object.
* `endpoint` should be a string or a `false` value (like `null` or `undefined`) that represents the Vulos Identity endpoint.
```javascript
// the constructor is called inside of the createAuth method of `Application`
import { BackendAuth } from "@vulos/identity-node-sdk"
const auth = applicaion.createAuth(BackendAuth)
```
{% hint style="info" %}
See [`Application`](/reference/identity-javascript-sdk/the-base-package/authentication/application) for more information.
{% endhint %}
### `async connect()`
Connect the authentication object to the Vulos Identity servers.
{% hint style="warning" %}
This should get called before any other functions.
{% endhint %}
```javascript
await auth.connect()
```
### `createVerifier()`
Create a verifier that other functions would take as an argument (as `authVerifier`).
{% hint style="info" %}
A verifier is an object that contains some value that will be used to verify if the server's response is valid.
{% endhint %}
{% hint style="success" %}
It's recommended create one verifier per authentication request.
{% endhint %}
```javascript
const verifier = auth.createVerifier()
```
### `async createAuthUrl(authVerifier)`
Create an authentication/consent URL for a user.
```javascript
const url = await auth.createAuthUrl(verifier)
// redirect the user to the URL
```
### `async processCallback(authVerifier, params)`
Process the callback URL query parameters (or fragment parameters if using the implicit flow) to get a [`User`](/reference/identity-javascript-sdk/the-base-package/authentication/user) object.
```javascript
// req is an object that is supposed to be a HTTP request in this example
const user = await auth.processCallback(verifier, req.query)
```
### `async getUserInfo(accessToken)`
Get an [`UserInfo`](/reference/identity-javascript-sdk/the-base-package/authentication/userinfo) object using an access token provided by OpenID.
```javascript
const userInfo = await auth.getUserInfo()
```
{% hint style="warning" %}
This probably shouldn't get called directly, use [`User.info()`](/reference/identity-javascript-sdk/the-base-package/authentication/user#async-info) instead.
{% endhint %}
### `async refreshTokens(refreshToken)`
Get a new OpenID token set using a refresh token.
```javascript
const { access_token, refresh_token, id_token, token_type, expires_at}
= await auth.refreshTokens(refreshToken)
```
{% hint style="warning" %}
This probably shouldn't get called directly, it's called automatically when needed.
{% endhint %}
# User
## Interfaces
### `UserTokens`
```typescript
interface UserTokens {
accessToken: string,
refreshToken: string,
idToken: string,
tokenType: string,
expiresAt: number
}
```
## Members
### `api :` [`BaseAuth`](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth)
The `BaseAuth` implementation that was used to create this object.
### `accessToken : string?`
This user's OpenID access token.
### `refreshToken : string?`
This user's OpenID refresh token.
### `idToken : string?`
This user's OpenID identification token.
### `tokenType : string?`
The type of the access token.
### `expiresAt : number?`
The time when the access token expires.
### `organizationApi :` [`OrganizationApi`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi)
The `OrganizationApi` object that is associated with this user.
### `profileApi :` [`ProfileApi`](/reference/identity-javascript-sdk/the-base-package/profile/profileapi)
The `ProfileApi` object that is associated with this user.
## Methods
### `constructor(api,tokens)`
Create a user object that interacts with the Vulos Identity API on behalf of a user.
* The `api` argument should be a [`BaseAuth`](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth) implementation;
* The `tokens` argument should be a token set that implements the [`UserTokens`](#tokens) interface.
```typescript
const user = new User(auth, preservedTokenSet)
// ... or
const user = await auth.processCallback(verifier, req.query)
```
{% hint style="info" %}
See [`BaseAuth`](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth) for more information.
{% endhint %}
### `save()`
Save the token set user to a serializable object that implements the [`UserTokens`](#tokens) interface.
{% hint style="info" %}
This function can be used if you want to store the user tokens in a database.
{% endhint %}
{% hint style="warning" %}
The tokens might update on any API call, so make sure you call this if you want to preserve the tokens.
{% endhint %}
```javascript
const tokenSet = user.save()
```
### `async reference()`
Create a [`UserReference`](/reference/identity-javascript-sdk/the-base-package/profile/userreference) object that is associated with this user.
```javascript
const ref = await user.reference()
```
### `async info()`
Get the [`UserInfo`](/reference/identity-javascript-sdk/the-base-package/authentication/userinfo) object for this user.
```javascript
const userInfo = await user.info()
```
### `async getOrganizationMemberships()`
Get all the [`OrganizationMembership`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationmembership) objects for this user's organizations.
```javascript
for (const membership of await user.getOrganizationMemberships()) {
// do something with the membership object
}
```
### `async createOrganization(details)`
Create a new organization with a `details` object that implements the [`OrganizationCreateDetails`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi#organizationcreatedetails) interface.
```javascript
const membership = await user.createOrganization({
name: 'My Organization',
website: 'https://example.com',
address: 'Example St. 1234',
uniqueId: '1234-567-89',
city: 'Example City',
countryCode: 'AQ',
zipCode: '1234',
// state: 'Optional State'
})
```
### `async organizationSearch(search, amount, offset)`
{% hint style="info" %}
This function is an alias to [`User.profileApi.organizationSearch()`](/reference/identity-javascript-sdk/the-base-package/profile/profileapi#async-organizationsearch-search-amount-offset).
{% endhint %}
The only difference is that this function doesn't throw, but returns `false` on failure.
### `async getAccessToken()`
Get the access token of the user.
{% hint style="info" %}
This function will automatically attempt to refresh the access token if it is expired.
{% endhint %}
```javascript
const accessToken = await getAccessToken()
```
# UserInfo
## Members
### `response : any`
The [OpenID userinfo endpoint](/identity/scopes-and-claims#user-info) response that this object was created with.
## Methods
### `constructor(response)`
Create an object that contains user information
```javascript
const response = await fetch(/* arguments to fetch the OpenID userinfo endpoint */)
.then(data => data.json())
const userInfo = new UserInfo(response)
// ... or
const userInfo = user.info()
```
{% hint style="warning" %}
This probably shouldn't get called directly, use [`User.info()`](/reference/identity-javascript-sdk/the-base-package/authentication/user#async-info) instead.
{% endhint %}
{% hint style="info" %}
See [`User`](/reference/identity-javascript-sdk/the-base-package/authentication/user) for more information.
{% endhint %}
{% hint style="info" %}
See [`BaseAuth`](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth) for more information.
{% endhint %}
### `id()`
Get an unique identifier about the user.
{% hint style="info" %}
This is the same as [`sub()`](#sub), it exists for readability.
{% endhint %}
{% hint style="warning" %}
This function requires the [`openid`](/identity/scopes-and-claims#openid) scope.
{% endhint %}
```javascript
const identifier = userInfo.id()
```
### `sub()`
Get an unique identifier about the user.
{% hint style="info" %}
This is the same as [`id()`](#id), it exists for readability.
{% endhint %}
{% hint style="warning" %}
This function requires the [`openid`](/identity/scopes-and-claims#openid) scope.
{% endhint %}
```javascript
const identifier = userInfo.sub()
```
### `firstName()`
Get the user's first name.
{% hint style="warning" %}
This function requires the [`profile`](/identity/scopes-and-claims#profile) scope.
{% endhint %}
```javascript
const firstName = userInfo.firstName()
```
### `lastName()`
Get the user's last name.
{% hint style="warning" %}
This function requires the [`profile`](/identity/scopes-and-claims#profile) scope.
{% endhint %}
```javascript
const lastName = userInfo.lastName()
```
### `birthDate()`
Get the user's birth date.
{% hint style="warning" %}
This function requires the [`profile`](/identity/scopes-and-claims#profile) scope.
{% endhint %}
```javascript
const birthDate = userInfo.birthDate()
// birthDate is a JavaScript Date object
```
### `nationalId()`
Get the user's unique national identifier (for example their SSN in the US).
{% hint style="warning" %}
This function requires the [`private`](/identity/scopes-and-claims#private) scope.
{% endhint %}
```javascript
const nationalId = userInfo.nationalId()
```
### `trustLevel()`
Get the user's Vulos Identity trust level.
* `1` indicates that the user has done no KYC verification but has provided basic details.
* `2` indicates that the user has successfully KYC verification.
* Anything other than that indicates that the user has done some action to reduce or increase their trust level that hasn't been specified in this document.
{% hint style="warning" %}
This function requires the [`public`](/identity/scopes-and-claims#public) scope.
{% endhint %}
```javascript
if (userInfo.trustLevel() >= 2) {
// allow the user to preform some action limited
// to users that have confirmed their identity
}
```
### `isEmailVerified()`
Get the user's email verification status.
{% hint style="warning" %}
This function requires the [`email`](/identity/scopes-and-claims#email) scope.
{% endhint %}
```javascript
if (userInfo.isEmailVerified()) {
// allow the user to use that email for some action
}
```
### `isKycVerified()`
Get the user's KYC verification status.
{% hint style="warning" %}
This function requires the [`public`](/identity/scopes-and-claims#public) scope.
{% endhint %}
```javascript
if (userInfo.isKycVerified()) {
// allow the user to do some action that requires
// KYC verification or a confirmed identity
}
```
### `address()`
Get the user's address.
{% hint style="warning" %}
This function requires the [`address`](/identity/scopes-and-claims#address) scope.
{% endhint %}
```javascript
const addressObj = userInfo.address()
```
### `email()`
Get the user's email address.
{% hint style="warning" %}
This function requires the [`email`](/identity/scopes-and-claims#email) scope.
{% endhint %}
```javascript
const email = userInfo.email()
```
### `hasRole(role)`
Check if the user has a specific role in the associated organization to the application.
{% hint style="warning" %}
This function requires the [`organization:roles`](/identity/scopes-and-claims#organization-roles) scope.
{% endhint %}
```javascript
if (userInfo.hasRole('SuperAdmin')) {
// allow the user to have elevated access
}
```
### `isInOrganizationWithName(name)`
Check if the user is in a specific organization by name.
{% hint style="warning" %}
This function requires the [`organization:read`](/identity/scopes-and-claims#organization-read) scope.
{% endhint %}
```javascript
if (userInfo.isInOrganizationWithName('My Organization')) {
// the user is in an organization with name 'My Organization'
}
```
{% hint style="warning" %}
It is recommended to use [`isInOrganizationWithId()`](#isinorganizationwithid-id) instead.
{% endhint %}
### `isInOrganizationWithId(id)`
Check if the user is in a specific organization by id.
{% hint style="info" %}
You can obtain the organization ID using the [Organization API](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi) or by checking the URL of the organization's page on the Vulos Identity dashboard.
{% endhint %}
{% hint style="warning" %}
This function requires the [`organization:read`](/identity/scopes-and-claims#organization-read) scope.
{% endhint %}
```javascript
const organizationId = 100;
if (userInfo.isInOrganizationWithId(organizationId)) {
// the user is in the organization with ID 100
}
```
### `wallets()`
Get the user's Ethereum wallet addresses.
{% hint style="warning" %}
This function requires the [`wallet`](/identity/scopes-and-claims#wallet) scope.
{% endhint %}
```javascript
for (const walletAddress of userInfo.wallets()) {
// do something with the wallet address
}
```
### `picture()`
Get the user's profile picture.
{% hint style="warning" %}
This function requires the [`profile`](/identity/scopes-and-claims#profile) scope.
{% endhint %}
```javascript
const profilePictureUrl = userInfo.picture()
```
# BaseApi
## Interfaces
### `SuccessResponse`
```typescript
interface SuccessResponse {
success: boolean,
message: string
}
```
## Members
### `user :` [`User`](/reference/identity-javascript-sdk/the-base-package/authentication/user)
The `User` that this API is associated with.
### `apiUrl : string`
The base URL of this API.
## Methods
### `constructor(user, apiUrl)`
This should only get called by classes that inherit the `BaseApi` class.
* `user` should be an instance of the [`User`](/reference/identity-javascript-sdk/the-base-package/authentication/user) object.
* `apiUrl` should be the base API URL.
```javascript
class SomeVulosIdentityApi extends BaseApi {
constructor(user, endpoint) {
super(user, endpoint + '/api/v1/some_api')
}
}
const someApi = new SomeVulosIdentityApi(user, endpoint)
```
### `async request(url, method = 'get', data = null, cachePrefix = null)`
Preform an authenticated request to the API.
```javascript
const response = await someApi.request('endpoint', 'put', { key: 'value' }, 'some:endpoint')
```
# Organizations
## Classes
{% content-ref url="/pages/LUH13OG0ncmaJNWUWMj2" %}
[Organization](/reference/identity-javascript-sdk/the-base-package/organizations/organization)
{% endcontent-ref %}
{% content-ref url="/pages/b6obHXRfB4NLhw7YWMDe" %}
[OrganizationMembership](/reference/identity-javascript-sdk/the-base-package/organizations/organizationmembership)
{% endcontent-ref %}
{% content-ref url="/pages/dqqWIoGBH2H73IiZc40a" %}
[OrganizationMembershipWithMetadata](/reference/identity-javascript-sdk/the-base-package/organizations/organizationmembership/organizationmembershipwithmetadata)
{% endcontent-ref %}
{% content-ref url="/pages/tm8bAVIJf0laVrDvJL34" %}
[OrganizationRole](/reference/identity-javascript-sdk/the-base-package/organizations/organizationrole)
{% endcontent-ref %}
{% content-ref url="/pages/SHkx195pI3vrwH67b49T" %}
[OrganizationApi](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi)
{% endcontent-ref %}
# Organization
## Members
### `memberships :` [`OrganizationMembership`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationmembership)`[]`
All the memberships that this organization has.
### `api :` [`OrganizationApi`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi)
The `OrganizationAPI` that this object was created with.
### `created : Date`
The date that the organization was created at.
### `id : number`
The ID of this organization.
### `name : string`
The name of this organization.
### `website : string`
The website URL of this organization.
### `address : string`
The address of this organization.
### `uniqueId : string`
The unique ID of this organization.
### `taxNumber : string`
The tax number of this organization.
### `city : string`
The city where this organization is based.
### `state : string`
The state where this organization is based.
### `verified : boolean`
The verification status of this organization.
### `zipCode : string`
The zip code where this organization is located.
### `counry : string`
The country where this organization is based.
## Methods
### `constructor(api, organization)`
Create a new Organization object using the [Organization API](/reference/organization-api).
* `api` must be an instance of [`OrganizationApi`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi);
* `organization` must implement the [`OrganizationInfo`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi#organizationinfo) interface.
```javascript
const details = await organizationApi.organizationInfo(organizationId)
const organization = new Organization(organizationApi, details)
```
### `async update(details)`
Update this organization's details.
The `details` object must implement the interface [`OrganizationUpdateDetails`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi#organizationupdatedetails).
The result is a boolean that indicates success.
```javascript
if (await organization.update({name: 'New Name'})) {
// the organization's name was updated successfully
}
```
### `async invite(email)`
Invite a user to this organization by email.
The result is a boolean that indicates success.
```javascript
if (await organization.invite(email)) {
// the user was invited successfully
}
```
### `async remove()`
Delete this organization.
The result is a boolean that indicates success.
```javascript
if (await organization.remove()) {
// the organization was deleted successfully
}
```
# OrganizationMembership
## Members
### `api :` [`OrganizationApi`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi)
The `OrganizationApi` that this object was created with.
### `organizationId : number`
The organization id that this membership is associated with.
### `membershipId : string`
The id of this membership.
### `userId : string`
The id of the user that this membership is associated with.
## Methods
### `constructor(api, membership)`
Create a new Membership object using the [Organization API](/reference/organization-api).
* `api` must be an instance of [`OrganizationApi`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi);
* `membership` must implement the [`OrganizationMembershipReference`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi#organizationmembershipreference) interface.
```javascript
const details = await organizationApi.organizationInfo(organizationId)
const [membershipData] = details.memberships
const membership = new OrganizationMembership(organizationApi, membershipData)
```
### `async addRole(name)`
Add a new role to this membership.
The result is an [`OrganizationRole`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationrole) object or `false` if it failed.
```javascript
const role = await membership.addRole('Admin')
```
### `async getRoles()`
Get all the roles associated with this membership.
The result is an array of [`OrganizationRole`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationrole) objects or `false` if it failed.
```javascript
const roles = await membership.getRoles()
```
### `async getOrganization()`
Get the organization associated with this membership.
The result is an [`Organization`](/reference/identity-javascript-sdk/the-base-package/organizations/organization) object or `false` if it failed.
```javascript
const organization = await membership.getOrganization()
```
### `reference()`
Create a [`UserReference`](/reference/identity-javascript-sdk/the-base-package/profile/userreference) object that is associated with this membership's user.
```javascript
const ref = membership.reference()
```
### `async organizationProfile()`
Get this membership's organization profile.
The result of this function implements the [`OrganizationProfileInfo`](/reference/identity-javascript-sdk/the-base-package/profile/profileapi#organizationprofileinfo) interface.
```javascript
const organizatonProfile = await membership.organizationProfile()
```
### `async remove()`
Remove this membership from the organization.
The result is a boolean that indicates success.
```javascript
if (await membership.remove()) {
// the membership was successfully removed from the organization
}
```
# OrganizationMembershipWithMetadata
{% hint style="info" %}
This class implements [`OrganizationMembership`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationmembership).
{% endhint %}
## Members
### `roles :` [`OrganizationRole[]`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationrole)
The roles associated with this membership.
### `firstName : string`
The first name of the user associated with this membership.
### `lastName : string`
The last name of the user associated with this membership.
### `email : string`
The email of the user associated with this membership.
## Methods
### `constructor(api, membership)`
Create a new Membership object using the [Organization API](/reference/organization-api).
* `api` must be an instance of [`OrganizationApi`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi);
* `membership` must implement the [`MembershipInfo`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi#membershipinfo) interface;
```javascript
const info = await organizationApi.memberInfo(organizationId, membershipId)
const membership = new OrganizationMembershipWithMetadata(organizationApi, info)
```
### `static async fromMembership(membership)`
Create a membership with metadata object from a normal membership.
```javascript
const membership = await OrganizationMembershipWithMetadata.fromMembership(normalMembershipObject)
```
### `override async getRoles()`
An override of [`OrganizationMembership.getRoles()`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationmembership#async-getroles) that doesn't send a request to get the roles.
```javascript
const roles = await membership.getRoles()
```
# OrganizationRole
## Members
### `api :` [`OrganizationApi`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi)
The `OrganizationAPI` that this object was created with.
### `id : string`
The id of this role.
### `name : string`
The name of this role.
### `member :` [`OrganizationMembership`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationmembership)
The membership that this role is associated with.
## Methods
### `constructor(api, member, role)`
Create a new role object using the [Organization API](/reference/organization-api).
* `api` must be an instance of [`OrganizationApi`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi);
* `member` must be an instance of [`OrganizationMembership`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationmembership);
* `role` must implement the [`RoleReference`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationapi#rolereference) interface;
{% hint style="warning" %}
This constructor should not be called directly, use [`OrganizationMembership.getRoles()`](/reference/identity-javascript-sdk/the-base-package/organizations/organizationmembership#async-getroles) instead.
{% endhint %}
### `async remove()`
Remove this role from the membership.
The result is a boolean that indicates success.
```javascript
if (await role.remove()) {
// the role was successfully removed from the membership
}
```
# OrganizationApi
{% hint style="info" %}
This class implements [`BaseApi`](/reference/identity-javascript-sdk/the-base-package/authentication/baseapi).
{% endhint %}
{% hint style="warning" %}
You need the [`organization:manage`](/identity/scopes-and-claims#organization-manage) scope to access this API.
{% endhint %}
{% hint style="info" %}
This is a JavaScript implementation of the [Organization API](/reference/organization-api).
{% endhint %}
{% hint style="success" %}
For ease of use we recommend using the [`User`](/reference/identity-javascript-sdk/the-base-package/authentication/user) object for interaction instead.
{% endhint %}
## Interfaces
### `RoleReference`
```typescript
interface RoleReference {
name: string,
id: string
}
```
### `MembershipInfo`
```typescript
interface MembershipInfo {
roles: RoleReference[],
firstName: string,
lastName: string,
email: string,
organizationId: number,
membershipId: string,
userId: string
}
```
### `OrganizationCreateDetails`
```typescript
interface OrganizationCreateDetails {
name: string,
website: string,
address: string,
uniqueId: string,
taxNumber: string,
city: string,
countryCode: string,
zipCode: string,
state?: string
}
```
### `OrganizationUpdateDetails`
```typescript
interface OrganizationUpdateDetails {
name?: string,
website?: string,
address?: string,
uniqueId?: string,
taxNumber?: string,
city?: string,
countryCode?: string,
zipCode?: string,
state?: string
}
```
### `OrganizationInfo`
```typescript
interface OrganizationInfo {
memberships: OrganizationMembershipReference[],
id: number,
name: string,
website: string,
address: string,
uniqueId?: string,
taxNumber: string,
city: string,
country: {
alpha2: string,
name: string
},
zipCode: string,
state: string,
verified: boolean,
created: number
}
```
### `OrganizationMembershipReference`
```typescript
interface OrganizationMembershipReference {
organizationId: number,
membershipId: string,
userId: string
}
```
## Methods
### `constructor(user, endpoint)`
Create an Organization API object.
* `user` should be an instance of the [`User`](/reference/identity-javascript-sdk/the-base-package/authentication/user) object.
* `endpoint` should be the Vulos Identity endpoint.
```javascript
const organizationApi = new OrganizationApi(user, endpoint)
```
### `async organizationList()`
Get a list of all the organizations that the user is in.
The result is an array of objects that implement the [`OrganizationMembershipReference`](#organizationmembershipreference).
{% hint style="info" %}
This method's response has the `organization:list` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
for (const membership of await organizationApi.organizationList()) {
// do something with the membership
}
```
### `async organizationInfo(id)`
Get information of an organization by the organization's ID.
The result implements the [`OrganizationInfo`](#organizationinfo) interface.
{% hint style="info" %}
This method's response has the `organization:info` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const info = await organizationApi.organizationInfo(organizationId)
```
### `async organizationUpdate(id, details)`
Update an organization's details.
The `details` object implements the [`OrganizationUpdateDetails`](#organizationupdatedetails) interface.
The result implements the [`SuccessResponse`](/reference/identity-javascript-sdk/the-base-package/authentication/baseapi#successresponse) interface.
{% hint style="info" %}
This method's response has the `organization:update` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const response = await organizationApi.organizationUpdate(organizationId, {name: 'New Organization Name'})
if (response.success) {
// the organization's name was updated successfully
}
```
### `async organizationDelete(id)`
Delete an organization.
The result implements the [`SuccessResponse`](/reference/identity-javascript-sdk/the-base-package/authentication/baseapi#successresponse) interface.
{% hint style="info" %}
This method's response has the `organization:delete` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const response = await organizationApi.organizationDelete(organizationId)
if (response.success) {
// successfully deleted the organization
}
```
### `async organizationCreate(details)`
Create a new organization.
The `details` object implements the [`OrganizationCreateDetails`](#organizationcreatedetails) interface.
The result implements the [`OrganizationMembershipReference`](#organizationmembershipreference) interface.
{% hint style="info" %}
This method's response has the `organization:create` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const membership = await organizationApi.organizationCreate({
name: 'My Organization',
website: 'https://example.com',
address: 'Example St. 1234',
uniqueId: '1234-567-89',
city: 'Example City',
countryCode: 'AQ',
zipCode: '1234',
// state: 'Optional State'
})
```
### `async memberInfo(id, member)`
Get information about a specific member.
* `id` is the organization id;
* `member` is the membership id;
The result implements the [`MembershipInfo`](#membershipinfo) interface.
{% hint style="info" %}
This method's response has the `organization:member:info` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const memberInfo = await organizationApi.memberInfo(organizationId, membershipId)
```
### `async memberDelete(id, member)`
Remove a member from an organization.
The result implements the [`SuccessResponse`](/reference/identity-javascript-sdk/the-base-package/authentication/baseapi#successresponse) interface.
{% hint style="info" %}
This method's response has the `organization:member:delete` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const response = await organizationApi.memberDelete(organizationId, membershipId)
if (response.success) {
// successfully deleted the membership
}
```
### `async memberInvite(id, email)`
Invite a user to an organization by email.
The result implements the [`SuccessResponse`](/reference/identity-javascript-sdk/the-base-package/authentication/baseapi#successresponse) interface.
{% hint style="info" %}
This method's response has the `organization:member:invite` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const response = await organizationApi.memberInvite(organizationId, email)
if (response.success) {
// successfully invited the member
}
```
### `async roleList(id, member)`
Get all the roles for a member.
The result is an array of objects that implement the [`RoleReference`](#rolereference) interface.
{% hint style="info" %}
This method's response has the `organization:role:list` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const roles = await organizationApi.roleList(organizationId, membershipId)
for(const role of roles) {
// do something with the role
}
```
### `async roleCreate(id, member, name)`
Add a new role to a user.
The result implements the [`RoleReference`](#rolereference) interface.
{% hint style="info" %}
This method's response has the `organization:role:create` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const role = await organizationApi.roleCreate(organizationId, membershipId, "Admin")
```
### `async roleDelete(id, member, role)`
Remove a role from a member.
* `role` is the role id;
The result implements the [`SuccessResponse`](/reference/identity-javascript-sdk/the-base-package/authentication/baseapi#successresponse) interface.
{% hint style="info" %}
This method's response has the `organization:role:delete` [cache](/reference/identity-javascript-sdk/the-base-package/cache#addpolicy-key-lifespan) prefix.
{% endhint %}
```javascript
const response = await organizationApi.roleDelete(organizationId, membershipId, roleId)
if (response.success) {
// successfully deleted the role
}
```
# The Backend Auth Package
This package contains the backend implementation for [`BaseAuth`](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth).
`npm install @vulos/identity-node-sdk --save`
## Classes
{% content-ref url="/pages/Y5iji8ovndpDivDcGaA0" %}
[CodeVerifier](/reference/identity-javascript-sdk/the-backend-auth-package/codeverifier)
{% endcontent-ref %}
{% content-ref url="/pages/0hjCk1zQx0oc6dJHkydn" %}
[BackendAuth](/reference/identity-javascript-sdk/the-backend-auth-package/backendauth)
{% endcontent-ref %}
# CodeVerifier
## Members
### `codeChallenge : string`
The OpenID code challenge.
### `codeChallengeMethod : string`
The OpenID code challenge method - defaults to `"S256"`.
### `codeVerifier : string`
The OpenID code verifier.
## Methods
### `constructor()`
Create a new code verifier.
```javascript
const verifier = new CodeVerifier()
```
# BackendAuth
{% hint style="info" %}
This class implements [`BaseAuth`](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth).
{% endhint %}
## Members
### `client : any | null`
An implementation specific OpenID connect client.
## Methods
This class only overrides previously defined methods from [`BaseAuth`](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth).
# The Frontend Auth Package
This package contains the frontend implementation for [`BaseAuth`](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth).
`npm install @vulos/identity-browser-sdk --save`
## Classes
{% content-ref url="/pages/cogqrvCcexWUFwQ5TSrS" %}
[StateVerifier](/reference/identity-javascript-sdk/the-frontend-auth-package/stateverifier)
{% endcontent-ref %}
{% content-ref url="/pages/AqcvcWOd9sojy4K09cgW" %}
[FrontendAuth](/reference/identity-javascript-sdk/the-frontend-auth-package/frontendauth)
{% endcontent-ref %}
## Functions
{% content-ref url="/pages/ejJGI51Finc69EceAidn" %}
[IFrameRefresh](/reference/identity-javascript-sdk/the-frontend-auth-package/iframerefresh)
{% endcontent-ref %}
# IFrameRefresh
This function is an `iframe`-based implementation for the [refresh token callback](/reference/identity-javascript-sdk/the-frontend-auth-package/frontendauth#async-setrefreshtokencallback-fn).
```javascript
import { IFrameRefresh } from '@vulos/identity-browser-sdk'
await auth.setRefreshTokenCallback(IFrameRefresh)
```
{% hint style="danger" %}
Before using this feature make sure your application fulfills the requirements and validate that the limitations won't cause issues for your application's user experience and flow.
{% endhint %}
{% hint style="warning" %}
If you are using a server-side rendered application you should use [The Backend Auth Package](/reference/identity-javascript-sdk/the-backend-auth-package) with a `code id_token` response type instead.
{% endhint %}
### Requirements
* That [`BaseAuth.processCallback()`](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth#async-processcallback-authverifier-params) is always the first thing that gets called when an OpenID fragment/hash is a part of the URL (in the route that is the default redirect URL);
* That the application doesn't execute/render anything that might initiate a token refresh while a token is already being refreshed;
* If a token is being refreshed in a specific frame, that frame shouldn't do anything else;
* If your application handles the window `message` event, it **MUST NOT** stop event propagation/bubbling (using `Event.stopPropagation()` or `return false` in an event handler), you can notice that an event is sent by [`BaseAuth.processCallback()`](/reference/identity-javascript-sdk/the-base-package/authentication/baseauth#async-processcallback-authverifier-params) if it has the `Event.data.accessToken` or `Event.data.fail` properties;
* That your application runs in a browser window that supports `