Using Authentication Tokens

Authentication tokens are essential when your custom widgets need to make API requests to secure endpoints or services that require user authentication. The Widget Builder provides access to Staffbase authentication tokens that can be used in your API requests.

Available Authentication Tokens

The Widget Builder provides two types of Staffbase authentication tokens that you can use in your API requests:

Staffbase ID Token

The ID Token is a JSON Web Token (JWT) that contains information about the authenticated user. It provides identity information that can be used to verify who the user is.

This is an example payload of the staffbase id token:

{
  "at_hash": "SfaFUUXInY8qOcHj-iMrtg",
  "aud": ["a5ba7f74-bedf-4d09-a4b0-ab84faf3ca7b"],
  "auth_time": 1758618864,
  "display_name": "Max Mustermann",
  "exp": 1758723348,
  "iat": 1758719748,
  "iss": "https://id-us1.staffbase.com/",
  "jti": "9df571d8-b9ab-4c90-9e7b-12f439139d88",
  "public_email": "max.mustermann@jasp.eu",
  "rat": 1758618861,
  "sid": "058855b2-ef8d-4eb4-9ccd-bb3f022e4a9c",
  "sub": "640b43f6fd99249009a41ba4"
}

How to access the ID Token

In your Handlebars templates, you can access the ID Token using the staffbaseIdToken helper:

<!-- Returns the jwt token -->
{{staffbaseIdToken}}

<!-- Returns a object -->
{{decode_jwt (staffbaseIdToken)}}

<!-- Returns a value from the payload -->
{{extract_jwt (staffbaseIdToken) "sub"}}

When to use the ID Token

Use the ID Token when:

• You need to authenticate with services that validate Staffbase users
• You need to access user identity information
• You're making API calls to services that accept Staffbase ID tokens for authentication
• You need to verify the user's identity on the server side

Example: Using the ID Token in an API request

<script>
async function fetchUserData() {
  const response = await fetch("https://api.example.com/user-data", {
    headers: { Authorization: "Bearer {{staffbaseIdToken}}" },
  });
  const data = await response.json();
  console.log("Response: ", data);
}
</script>

Staffbase Access Token

The Access Token is used to grant access to specific resources or services. Unlike the ID Token, which is primarily for identification, the Access Token is for authorization purposes.

How to access the Access Token

In your Handlebars templates, you can access the Access Token using the staffbaseAccessToken helper:

{{staffbaseAccessToken}}

This helper returns the token as a string that typically looks like:

ory_ae4b742ea3...

When to use the Access Token

Use the Access Token when:

• You need to make requests to Staffbase APIs or services
• You need to authenticate with third-party services that have been integrated with Staffbase
• You need to authorize specific actions rather than just identify the user
• You're making API calls that require permissions to access specific resources

Example: Using the Access Token in an API request

<script>
async function fetchProtectedResource() { 
    const response = await fetch('https://app.staffbase.com/api/users', { 
        headers: { 'Authorization': 'Basic {{staffbaseAccessToken}}' } 
    }); 
    const data = await response.json();
    document.getElementById('resource-data').textContent = JSON.stringify(data); 
}
</script>

Third Party Connections Tokens

You can add the access token from the Microsoft, Google Workspace, ServiceNow, Atlassian or Box connections to your request. Please contact our support for instructions.

Adding Authentication to API Requests in Widget Builder

When creating API requests in the Widget Builder, you can easily add authentication using the Staffbase tokens:

1. In the Widget Builder, navigate to the "API" tab
2. Create or edit an API request
3. In the Headers section, add an Authorization header:
   • For ID Token: Authorization: Bearer {{staffbaseIdToken}}
   • For Access Token: Authorization: Bearer {{staffbaseAccessToken}}

Security Considerations

When working with authentication tokens, keep these security best practices in mind:

• Don't store tokens in localStorage or sessionStorage for extended periods
• Use HTTPS for all API requests to ensure tokens are encrypted during transmission

Troubleshooting

If you encounter issues with authentication tokens:

1. Verify token format: Ensure you're using the correct format for the Authorization header
2. Check CORS settings: Cross-Origin Resource Sharing restrictions might block your requests
3. Inspect network requests: Use browser developer tools to see the actual request and response
4. Verify API permissions: Ensure the API endpoint accepts the type of token you're using

Example Implementation

Here's a complete example of a widget that uses both types of tokens:

<div class="authenticated-widget">
  <h2>User Profile</h2>
  <div id="user-data">Loading...</div>

  <button onclick="fetchUserProfile()">Load Profile</button>
  <button onclick="fetchUserResources()">Load Resources</button>

  <script>
    // Using ID Token to get user information async function fetchUserProfile()
    function fetchUserProfile() { 
        try { 
            const response = await fetch('https://api.example.com/profile', {
                headers: { 'Authorization': 'Bearer {{staffbaseIdToken}}' } 
            }); 
            if (!response.ok) throw new Error('Failed tofetch profile'); 
            const data = await response.json();
            document.getElementById('user-data').innerHTML = `<p>Name: ${data.name}</p><p>Email: ${data.email}</p>`; 
        } catch (error) {
            document.getElementById('user-data').textContent = 'Error: ' + error.message; 
        } 
    } 

    // Using Access Token to get protected resources async
    function fetchUserResources() { 
        try { 
            const response = await fetch('https://app.staffbase.com/api/users', { 
                headers: { 'Authorization': 'Basic {{staffbaseAccessToken}}' } 
            }); 
            if (!response.ok) throw new Error('Failed to fetch resources'); 
            const data = await response.json();
            document.getElementById('user-data').innerHTML = `<h3>Your Resources</h3><pre>${JSON.stringify(data, null, 2)}</pre>`; 
        } catch (error) {
            document.getElementById('user-data').textContent = 'Error: ' + error.message; 
        } 
    }
  </script>
</div>

By understanding the differences between ID and Access tokens and when to use each, you can create secure and powerful custom widgets that integrate with various services while maintaining proper authentication.