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 identification from your system (could be the username, id, or email). 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).