Authentication

Authentication is required for user data endpoints / actions in the form of a Vezgo user token.

API clients (both frontend and backend) will need to obtain a token before making user data API calls for or opening the Vezgo Connect widget.

The token must be included in the Authorization: Bearer ${token} header in your Vezgo API request, or in the ?token= query string in the Vezgo Connect widget URL.

The token is short-lived and you will need to obtain a new one when it expires. Currently the default token lifetime is 10 minutes.

Backend clients

The Vezgo user token can be requested by POSTing to {VEZGO_API_URL}/auth/token with:

• Your team's Client Id and Client Secret, which you get when signing up for Vezgo API. Passed as clientId & secret in request body JSON.
• The user's unique identifier from your system (such as an internal user ID, UUID, customer number, or API token, but avoid using PII like emails or usernames). Passed as loginName in request header.

POST /auth/token HTTP/1.1
Host: api.vezgo.com
Content-Type: application/json
loginName: USERNAME_FROM_YOUR_SYSTEM

{
  "clientId": "YOUR_CLIENT_ID",
  "secret": "YOUR_CLIENT_SECRET"
}

The endpoint returns the following JSON:

{
  "token": "YOUR_USER_TOKEN"
}

Backend

const vezgo = Vezgo.init({
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
});

const user = vezgo.login('USERNAME_FROM_YOUR_SYSTEM');
const token = await user.getToken();

Shell

curl '{VEZGO_API_URL}/auth/token' \
  -X POST \
  -H 'loginName: USERNAME_FROM_YOUR_SYSTEM' \
  -H 'Content-Type: application/json' \
  -d '{
      "clientId": "YOUR_CLIENT_ID",
      "secret": "YOUR_CLIENT_SECRET"
  }'

Frontend client

Because the secret is required to obtain a user token, it will always need to be requested from your backend server which is supposed to store secret securely. Your frontend client will need to obtain a token via your backend server.

Your backend server could serve a /vezgo/token endpoint which authenticates and requests a user token on behalf of your frontend client.

Frontend

const vezgo = Vezgo.init({
  clientId: 'YOUR_CLIENT_ID',
  authEndpoint: '/vezgo/auth', // default value, your server should implement this endpoint
  auth: {
    params: { username: 'USERNAME_FROM_YOUR_SYSTEM' }
  }
});

const user = vezgo.login();
const token = await user.getToken();

Backend

const vezgo = Vezgo.init({
  clientId: 'YOUR_CLIENT_ID',
  secret: 'YOUR_CLIENT_SECRET',
});

app.post('/vezgo/auth', async (req, res) => {
  // Replace with your own authentication
  const { username } = req.body;
  const user = vezgo.login(username);

  res.json({ token: await user.getToken() });
});

caution

secret must be securely stored and kept secret. You must never expose it in your frontend client (be it your website or mobile app).