Connecting Securely to Willba API

This guide provides a walkthrough on the secure procedure for integrating third-party applications with the Willba API.

🔒 Important: This documentation is for developers and entities aiming to integrate with Willba API

1. Get Your JWT Client Credentials

Ask access to the Willba API from your Willba administrator contact person. You will get the following credentials.

• client_id
• client_secret
• realm token URL: https://auth.willba.app/realms/{realm-name}/protocol/openid-connect/token

tip

Remember, {realm-name} refers to the environment tenant name, given by the administrator.

2. Get Your Access Token

To communicate with Willba API, you always need to have a valid JWT access token. To get the required access token in your app do the following:

• Construct a POST request targeting the realm token URL.
• Insert the client_id, client_secret, and grant_type (which should be 'client_credentials') in the request body.

Replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, and {realm-name} with their corresponding real values.

POST request:

Bash

curl -X POST \
    -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "grant_type=client_credentials" \
     "https://auth.willba.app/realms/{realm-name}/protocol/openid-connect/token"

Javascript

const axios = require('axios');
const qs = require('qs');

const credentials = {
  client_id: 'YOUR_CLIENT_ID',
  client_secret: 'YOUR_CLIENT_SECRET',
  grant_type: 'client_credentials'
};

axios.post("https://auth.willba.app/realms/{realm-name}/protocol/openid-connect/token", qs.stringify(credentials), {
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Error obtaining token:', error);
});

Response:

Bash

{
    "access_token": "eyJhbG...V82q3IQ",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "email profile"
}

Javascript

{
    "access_token": "eyJhbG...V82q3IQ",
    "expires_in": 300,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "email profile"
}

Once the request is successful, you'll receive an access_token in the response. This token is crucial and should be included in all requests to Willba's API. You need to obtain a new access token every time you need to access API and previous access token has expired.

caution

It's essential to treat the access_token with the confidentiality. Prevent its exposure to unauthorized individuals or apps. Also, always opt for secure connections when transmitting this token.

3. Embed Access Token in Request Headers

For any API request to Willba, make sure to append the access_token in the header as: Authorization: Bearer ${access_token}

Use the following examples to see how to attach the token to your API requests:

Bash

# Sample API call with cURL
curl -X GET \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     "https://api.willba.app/some-endpoint"

Javascript

// Sample API call with JavaScript (axios)
const axios = require('axios');

const token = 'YOUR_ACCESS_TOKEN';

axios.get("https://api.willba.app/some-endpoint", {
headers: {
'Authorization': `Bearer ${token}`
}
})
    .then(response => {
    console.log(response.data);
})
    .catch(error => {
    console.error('Error making API request:', error);
});

Remember to replace YOUR_ACCESS_TOKEN with the actual access_token value you receive.