In order to access Pavelink's API, a request for API credentials needs to be made. This request can be sent to our support desk at support@topcon.com. In this email, please include:
Our support desk will validate the request, and, if approved, will send you a Client ID and Client Secret. These credentials will be used to authenticate with Pavelink's API.
After receiving credentials, you can now start interfacing with Pavelink's API.
Two distinct Pavelink environments exist. Topcon recommends creating users and client credentials on both environments to ensure adequate isolation of development and production activity. Credentials for both environments can differ.
Pavelink's API relies on OAuth2's Authorization Code flow for authentication, specifically Resource Owner Password Credentials. Using the Client ID and Client Secret credentials we received, we can retrieve an access token from the API. This access token will be valid for one hour, after which it will expire and a new access token has to be requested by using a refresh token (more on this later).
| Environment Name | URL |
|---|---|
| Sandbox | https://pavelink.topcon.io/v1/sandbox/ |
| Production | https://pavelink.topcon.io/v1/production/ |
Let's see how we can retrieve an access token. The API has a specific /token endpoint for all communications regarding authorization; we can use this endpoint to retrieve access token, but also to refresh them when they have expired.
To get an access token, the following request needs to be made:
POST https://pavelink.topcon.io/v1/{environment}/token
| Content-Type | application/x-www-form-urlencoded |
grant_type=client_credentials&client_id={clientID}&client_secret={clientSecret}Note that the {environment} in the URL needs to be replaced with the name of the environment you wish to connect to. The {clientID} and {clientSecret} need to be replaced with the actual credentials you received.
Important
The /token endpoint is the only endpoint in Pavelink's API that only accepts requests that contain the Content-Type header described above. All other endpoints will only accept JSON, and will also return JSON
Executing the above request will (if the credentials are valid) result in a JSON response from the API, which will look similar to this:
{
"access_token": "xx123xx45678x901xx23456x7890xx12x34567x8x9012xx34xxxxx56",
"token_type": "bearer",
"expires_in": 3599,
"refresh_token": "123x4x5xx678xx9x012x345x6x789x01x2345x6x7xx890xxxxx1x2x34"
}The access_token and refresh_token are the most important properties in this response. Congratulations, now that we have an access token, we are authorized with Pavelink's API, and we can continue to do some operations on the API.
Let's use the access token retrieved in step 1 execute a GET request on the API to retrieve all of our organisation's divisions.
Divisions depend on your organisation
Depending on how your organisation is structured within Pavelink it is possible that you have one division, or multiple. This example will work for both structures.
To get all divisions, we can use the /divisions endpoint, on which we can perform a simple GET request. This request should like like this:
GET https://pavelink.topcon.io/v1/{environment}/divisions
| Content-Type | application/json |
| Authorization | Bearer {accessToken} |
Empty
Again, like in the request we've made in step 1, we should replace all variables with their actual values. For the authorization header, we need to include the entire access token we've received in the response in step 1. Executing this GET request will result in a response with a list of division objects. The response could look like this:
[
{
"id": "60c0f3b7-3323-4073-b456-44db2cd66f9a",
"name": "TOPCON Eindhoven",
"abbreviation": "TC01"
}
]In this response we have a single division object in the list. However, multiple division objects are also possible if your organisation is structured like this. The division name and abbrevation are present, but also its ID in the form of a UUID. This ID is important in other endpoints, where you need to supply the division ID when, for example, creating a project.
Now you have enough information to perform all kinds of operations on Pavelink's API, but there is one remaining topic we should cover: refreshing access tokens when they have expired.
The access tokens issued for Pavelink's API are valid for one hour. After one hour, the access token expires, and it needs to be refreshed. In line with OAuth2's refresh token flow, we use the refresh token that was issued during the first authorization call made in step 1. Let's look at such a refresh request (it looks very similar to the initial authorization call from step 1):
POST https://pavelink.topcon.io/v1/{environment}/token
| Content-Type | application/x-www-form-urlencoded |
grant_type=refresh_token&client_id={clientID}&client_secret={clientSecret}&refresh_token={refreshToken}Note that the grant_type has changed, and that we include the entire refresh_token we've received in the authorization response in step 1.
Executing this request will grant us an identical response as the one in step 1, with a new access token as well as a new refresh token. This access token is again valid for one hour. Refresh tokens for the API are valid indefinitely, but after a refresh call has been made, the used refresh token is no longer valid and should be replaced with the new refresh token.
We recommend to implement refreshing the access token in a reactive way, instead of a time-based way. Because of the time window of one hour in which access tokens are valid, we've seen customers implement a refresh cycle which runs every hour. However, depending on the amount of requests your application will perform on Pavelink's API, this could result in race conditions and requests failing because the access token is no longer valid while a refresh operation is in-flight.
Hence, we recommend implementing a piece of middleware which will monitor the validity of the access token, and buffer requests when the access token expires. All of your application's requests will be piped through this middleware, and it should inspect the response codes for all these requests. As soon as a request receives a response with HTTP status code 401 Unauthorized, the access token is no longer valid. All requests currently in-flight, as well as requests being made after this moment, should be buffered. While the buffer is active, a refresh call should be made to retrieve a new access token. After this new access token is known, all requests in the buffer should have their headers modified to include the new (valid) access token. The buffer can then be emptied, and all operations can continue as normal.
The credentials provided by Topcon give the authenticated application full read/write permissions within the API. Be aware of this when performing potentially destructive operations with the API.