---
title: "Logging In to the NavVis IVION REST API"
slug: "logging-in"
description: "Access NavVis IVION data securely with third-party applications through a streamlined authorization process and manage access tokens efficiently."
updated: 2025-09-22T10:53:30Z
published: 2025-09-22T10:53:30Z
canonical: "knowledge.navvis.com/logging-in"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.navvis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Logging In

NavVis IVION provides a mechanism for third-party applications to request access to the API and the data stored on a particular NavVis IVION Instance.

The consuming application should request a login mandate to begin the authorization process through the following endpoint:

```plaintext
POST {instance_url}/api/auth/mandate/request
```

Response Code & Status

```plaintext
200 OK
```

Response Body:

```plaintext
{
	"exchange_token": string,
 	"authorization_token": string,
	"expiration": string
}
```

This POST request doesn't require a body. The returned exchange and authorization tokens are 30 characters long ASCII alphanumeric strings. The expiration is a UNIX timestamp in seconds.

Once the login mandate is created, the consuming application should open a browser/webview window pointing to the URL below:

```plaintext
{instance_url}?mandate={authorization_token}&supplicant={application_name}
```

> [!NOTE]
> **Note**: The authorization token is the one previously returned by the 'request' endpoint.

> [!NOTE]
> **Note**: The supplicant query parameter is optional. If provided, it should be an URL-encoded version of the name of the consuming application.

![Authorize_Request](https://cdn.document360.io/bf174766-fa1a-4fe1-a4d7-b1db1e7cb996/Images/Documentation/Authorize_Request.jpg)

Once the browser window is open, the application begins polling the following endpoint at intervals (every 3 to 5 seconds):

```plaintext
GET {instance_url}/api/auth/mandate/validate?authorization_token={authorization_token}
```

Response Code & Status:

```plaintext
200 OK
```

Response Body:

```plaintext
{
	"authorized": boolean, 
	"excahnged": boolean, 
	"expired": boolean
}
```

The returned boolean values describe the state of the mandate associated with the supplied authorization token. If all the 3 attributes are **false**, the application should keep on polling the endpoint. As soon as the **authorized**attribute becomes **true**and the two other attributes are **false**, the application should proceed to the next step of the authorization process. If the **expired**attribute becomes **true**, the application should stop polling and request a new mandate. The **exchanged**attribute will never become true at this stage if the application implements the login flow properly.

| **Attribute** | **Description** |
| --- | --- |
| Authorized | Indicates whether the mandate has been successfully authorized by the user (the user has clicked on 'Allow') |
| Exchanged | Shows if the mandate has already been exchanged for credentials |
| Expired | Shows if the mandate has expired |

Once the mandate is authorized, the application can exchange it for access credentials by calling the following endpoint:

```plaintext
POST {instance_url}/api/auth/mandate/exchange
```

Request Body:

```plaintext
{
	"exchange_token": string
}
```

Response Code & Status:

```plaintext
200 OK
```

Response Body:

```plaintext
{
	"access_token": string, 
	"refresh_token": string, 
	"principal": 
	{
		"username": string,
		"first_name": string | null, 
		"last_name": string | null, 
		...
	}, 
	...
}
```

> [!NOTE]
> **Note**: This endpoint requires the exchange token of the log in mandate and not the authorization token.

> [!NOTE]
> **Note**: The response to this call contains the access token needed for using the NavVis IVION API along with other information about the authorizing user. For detailed information about this response, see the [API documentation](https://apidocs.navvis.com/) page.

> [!NOTE]
> **Note**: The access token usually has a short validity and must be refreshed regularly by using the refresh token which is also part of the response. See [Refreshing the Access Token](/v1/docs/refreshing-the-access-token) for more information on this topic.

Application Programming Interface

A NavVis IVION instance is a copy of the NavVis IVION software running on a hosting server. An instance has a database which contains the associated datasets, users, and more. That data is accessible via the instance URL.