# Scopes and Claims

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.md#async-info) in the [JavaScript SDK](/reference/identity-javascript-sdk.md).

{% hint style="info" %}
See [`UserInfo`](/reference/identity-javascript-sdk/the-base-package/authentication/userinfo.md) for more information.
{% endhint %}

## User Info

<mark style="color:blue;">`GET`</mark> `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<mark style="color:red;">\*</mark> | String | Bearer authentication with the access token obtained using OpenID Connect |

{% tabs %}
{% tab title="200: OK An object that contains claims" %}

```javascript
{ "sub": "<guid>", ... }
```

{% 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": "<guid>"
}
```

{% 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": "<link to profile picture>",
    "given_name": "John",
    "family_name": "Doe",
    "birthdate": "YYYY-MM-DD"
}
```

{% endtab %}
{% endtabs %}

### `profile:read`

Provides access to the [Profile API](/reference/profile-api.md).

### `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": "<national id>",
    "digital_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": [
        "<ethereum wallet address>", 
        "<ethereum wallet address 2>"
    ]
}

// ... or

{
    "wallet_address": "<ethereum 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.md);

#### `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.md)
{% 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.md)
{% 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;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.vulos.io/identity/scopes-and-claims.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.