Using Puzzel ID Access Tokens

Overview

Puzzel ID access tokens provide secure authentication for accessing Puzzel APIs and services. This guide explains how to configure OIDC clients, obtain access tokens, and use them to authenticate with Puzzel services like the Contact Centre Web Services API.

Prerequisites

Before you can use Puzzel ID access tokens, you need to:

  • Have administrator access to your Puzzel organization settings
  • Understand the basic concepts of OAuth 2.0 and OpenID Connect (OIDC)
  • Know which Puzzel services you want to access

Setting Up an OIDC Client

Accessing OIDC Client Configuration

  1. Navigate to your Organisation Settings home page
  2. Click on the OIDC Clients section using the navigation menu
  3. You'll see a list of existing OIDC clients (if any) and options to create new ones

Creating a New OIDC Client

  1. Click the Add button from the OIDC Clients main page
  2. Fill in the required information:
    • Client name: A descriptive name for your client (this is not the client ID)
    • Grant type: Choose the appropriate OAuth grant type, for APIs use:
      • Client Credentials: For backend services and daemon applications
    • Description: Add a clear description of your client's purpose
    • Allowed Scopes: Specify the access level and permissions needed

Understanding Scopes

The following general scopes are available:

  • profile: Returns basic profile information claims
  • openid: Returns the sub claim that uniquely identifies the user
  • email: Returns email address and verification status
  • roles: Returns role names assigned to the user
  • groups: Returns group membership information
  • masterdata: Puzzel Masterdata related claims
  • contact-centre: Puzzel Contact Centre related claims

For Contact Centre Web Services, ensure your allowed scopes include at least:

  • contact-centre

Configuring Client Details

After saving your initial client configuration, you'll be taken to the client's detailed configuration page where you can set :

Security Settings

  • Grant type: Confirm your selected grant type
  • Require Client Secret: Enable for secure authentication
  • Allowed CORS Origins: Specify origins for JavaScript clients

Token Lifetimes

  • Identity Token Lifetime: How long ID tokens remain valid
  • Access Token Lifetime: How long access tokens remain valid
  • Refresh Token Settings: Configure refresh token behavior

Important: Avoid setting long lifetimes for access tokens. Due to signing key rotation in the Puzzel ID provider, tokens with extended lifetimes may become invalid before their expiration time. This is a security best practice that ensures tokens cannot be used indefinitely if compromised.

Adding Client Secrets

Creating a Shared Secret

  1. From your client's main page, click Manage Client Secrets
  2. Click Add and select Shared secret
  3. Add a description and set an expiration time
  4. Important: Copy the generated secret value immediately - it won't be shown again
  5. Store the secret securely and click Save

Alternative: Private Key JWT

For enhanced security, you can use Private Key JWT authentication:

  1. Select Private Key JWT when adding a secret
  2. Provide a base64 encoded X.509 certificate or JSON Web Key formatted RSA/EC key
  3. The expiration time will be extracted from your certificate or key

Configuring Product Access

For Contact Centre Web Services

  1. From the client list, click the key symbol for your client
  2. Click Add to associate a product-specific user
  3. Select Contact Centre (PCC) as the platform
  4. Choose your solution from the dropdown
  5. Either select an existing user or create a new one: Creating a new user:
    • Select the appropriate user group
    • Choose user type: Person, API, Wallboard, or Chatbot
    • Enter a unique username
  6. Important: Note the User ID of the added user - you'll need this for API requests. You can also use the "copy to clipboard" icon on an associated user to copy the full scope needed in the request later.
  7. Also note your Client ID for authentication requests


Obtaining Access Tokens

Making a Token Request

Use the client credentials flow to obtain an access token:

http
POST https://app.puzzel.com/id/connect/token
Content-Type: application/x-www-form-urlencoded  client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=contact-centre:TENANT_ID:USER_ID&grant_type=client_credentials

Request Parameters

  • client_id: Your registered OIDC client ID
  • client_secret: The secret associated with your client
  • scope: The scope string including tenant ID and user ID (format: contact-centre:TENANT_ID:USER_ID)
  • grant_type: Must be client_credentials for machine-to-machine authentication

Successful Response

A successful request returns:

json
{   "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",   "expires_in": 900,   "token_type": "Bearer",   "scope": "contact-centre" }

Using Access Tokens

Making Authenticated API Requests

Include the access token in the Authorization header:

http
GET https://app.puzzel.com/contactcentre5/your-endpoint
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...

Testing Your Access Token

Verify your token is valid by calling the token information endpoint:

http
GET https://app.puzzel.com/contactcentre5/accesstokeninformation
Authorization: Bearer YOUR_ACCESS_TOKEN

A successful response confirms your token is valid and properly scoped.

Best Practices

Security

  • Store client secrets securely and never expose them in client-side code
  • Use appropriate token lifetimes - shorter is generally more secure
  • Implement proper token refresh logic for long-running applications
  • Consider using Private Key JWT for enhanced security

Token Management

  • Monitor token expiration times (expires_in field)
  • Implement automatic token refresh before expiration
  • Handle authentication errors gracefully
  • Log authentication events for debugging

Environment Considerations

  • The examples use app.puzzel.com - ensure you're using the correct URI for your region
  • For on-premises deployments, use your specific base URI
  • Consult the Puzzel API Documentation for region-specific endpoints

Troubleshooting

Common Issues

401 Unauthorized:

  • Check that your access token is valid and not expired
  • Verify the token includes the required scopes
  • Ensure the Authorization header is properly formatted

403 Forbidden:

  • Verify your client has the necessary product access configured
  • Check that the user associated with your client has appropriate permissions

Invalid Client:

  • Confirm your client ID and secret are correct
  • Verify your client is enabled and not expired
  • Check that your grant type matches your client configuration

Getting Help

For additional support:

  • Consult the Puzzel API Documentation for detailed API references
  • Use the API Explorer for interactive testing
  • Contact Puzzel support for organization-specific issues

Related Resources

 
Back to Top

Published

Last updated

0
0

Recent documents

Popular documents