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:

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

Response Code & Status

200 OK

Response Body:

{
	"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:

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

Note: The authorization token is the one previously returned by the 'request' endpoint.

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

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

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

Response Code & Status:

200 OK

Response Body:

{
	"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.

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

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

Request Body:

{
	"exchange_token": string
}

Response Code & Status:

200 OK

Response Body:

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

Note: This endpoint requires the exchange token of the log in mandate and not the authorization token.

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 SwaggerHub page.

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 for more information on this topic.