Worldly Public API Authentication Guide

This guide explains how to authenticate requests to the Worldly Public API, including how to generate and use the required headers.

Overview

Every Worldly API request requires two authentication headers:

Header	Description
`x-api-key`	Your Developer Account API Key, created on the Worldly platform.
`x-developer-request-token`	A dynamic, encrypted token generated using your Integration Account API Key, a current UTC timestamp, and your Developer Public Key.

Note: The x-developer-request-token expires every 12 hours. You must regenerate it periodically to maintain access.

Prerequisites

Before beginning, ensure you have the following:

A valid Developer Account API Key
A valid Integration Account API Key
The Developer Public Key (public.pem) downloaded from the Worldly Platform
- Profile > Account Settings > Integrations
OpenSSL installed
- macOS default path: /opt/homebrew/bin/openssl
- Windows: Win32 OpenSSL

macOS / Linux Instructions

1. Set Environment Variables

export WORLDLY_DEVELOPER_API_KEY='your-developer-api-key'
export WORLDLY_INTEGRATION_API_KEY='your-integration-api-key'

Check both values are set correctly:

echo ${#WORLDLY_DEVELOPER_API_KEY} ${#WORLDLY_INTEGRATION_API_KEY}

Both numbers should be non-zero.

2. Create the Plaintext Token String

Combine your Integration Key and the current UTC timestamp with an ampersand (&) separator:

printf '%s' "${WORLDLY_INTEGRATION_API_KEY}&$(date -u +'%Y-%m-%dT%H:%M:%SZ')" > secret.txt

This file must contain a single line without a trailing newline.

Example content:

integration-key-value&2025-10-09T22:14:00Z

3. Encrypt Using Your Developer Public Key

Encrypt the string with your Developer Public Key, then Base64-encode it.

/opt/homebrew/bin/openssl pkeyutl -encrypt -pubin \
  -inkey /path/to/public.pem \
  -in secret.txt | base64 | tr -d '\r\n' > token.b64

Save the output token to an environment variable:

export WORLDLY_DEV_REQ_TOKEN=$(cat token.b64)

4. Send an API Request

curl -X GET "https://api-v2.production.higg.org/pic-api/v1/taxonomy-categories" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${WORLDLY_DEVELOPER_API_KEY}" \
  -H "x-developer-request-token: ${WORLDLY_DEV_REQ_TOKEN}"

5. Troubleshooting

Error or Symptom	Likely Cause	Fix
`pkeyutl: Error loading key`	Incorrect or missing `public.pem` path	Provide full path and confirm file starts with `-----BEGIN PUBLIC KEY-----`
`No such file or directory`	Path typo	Verify `public.pem` and `secret.txt` exist
`curl: (43) A libcurl function was given a bad argument`	Header contains newline or is empty	Rebuild token using `tr -d '\r\n'`
`401 Unauthorized`	Expired or invalid token	Regenerate with fresh timestamp
Empty token	Encryption failed	Recheck key path and repeat generation steps

6. Example: Full Script (macOS/Linux)

#!/bin/bash
export WORLDLY_DEVELOPER_API_KEY='your-developer-api-key'
export WORLDLY_INTEGRATION_API_KEY='your-integration-api-key'
PUBKEY='/path/to/public.pem'

TS="$(date -u +'%Y-%m-%dT%H:%M:%SZ')"
WORLDLY_DEV_REQ_TOKEN="$(
  printf '%s' "${WORLDLY_INTEGRATION_API_KEY}&${TS}" \
  | /opt/homebrew/bin/openssl pkeyutl -encrypt -pubin -inkey "$PUBKEY" -in /dev/stdin \
  | base64 | tr -d '\r\n'
)"

curl -v "https://api-v2.production.higg.org/pic-api/v1/products/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${WORLDLY_DEVELOPER_API_KEY}" \
  -H "x-developer-request-token: ${WORLDLY_DEV_REQ_TOKEN}" \
  --data '{"from":0,"size":10}'

7. Token Renewal

Tokens expire after 12 hours.
Add this script to a cron job or automated workflow that runs twice daily.

Windows / PowerShell Instructions

1. Set Environment Variables

$env:WORLDLY_DEVELOPER_API_KEY = "your-developer-api-key"
$env:WORLDLY_INTEGRATION_API_KEY = "your-integration-api-key"

Confirm they’re set:

Write-Host "Developer key length:" $env:WORLDLY_DEVELOPER_API_KEY.Length
Write-Host "Integration key length:" $env:WORLDLY_INTEGRATION_API_KEY.Length

2. Create the Plaintext String

$timestamp = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
$plainText = "$($env:WORLDLY_INTEGRATION_API_KEY)&$timestamp"
Set-Content -Path secret.txt -Value $plainText -NoNewline -Encoding ASCII

3. Encrypt and Encode

$pubKey = "C:\Path\To\public.pem"

$token = & openssl pkeyutl -encrypt -pubin -inkey $pubKey -in secret.txt |
          openssl base64 -A
$token = $token -replace "`r","" -replace "`n",""
$env:WORLDLY_DEV_REQ_TOKEN = $token

Check token length:

Write-Host "Token length:" $env:WORLDLY_DEV_REQ_TOKEN.Length

4. Send API Request

$uri = "https://api-v2.production.higg.org/pic-api/v1/products/search"
$body = '{"from":0,"size":10}'
$headers = @{
    "Content-Type" = "application/json"
    "x-api-key" = $env:WORLDLY_DEVELOPER_API_KEY
    "x-developer-request-token" = $env:WORLDLY_DEV_REQ_TOKEN
}

$response = Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body
$response | ConvertTo-Json -Depth 5

5. Troubleshooting

Symptom	Likely Cause	Fix
`pkeyutl: Error loading key`	Wrong path or invalid public key	Verify full path and file format
`Invoke-RestMethod` connection error	Token contains newline	Remove `\r` and `\n` using `-replace`
401 Unauthorized	Token expired	Regenerate with new timestamp
Empty token	Encryption failed	Confirm key path and rerun steps

6. Example: Full PowerShell Script

# Configuration
$env:WORLDLY_DEVELOPER_API_KEY = "your-developer-api-key"
$env:WORLDLY_INTEGRATION_API_KEY = "your-integration-api-key"
$pubKey = "C:\Path\To\public.pem"

# Token generation
$timestamp = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
$plainText = "$($env:WORLDLY_INTEGRATION_API_KEY)&$timestamp"
Set-Content -Path secret.txt -Value $plainText -NoNewline -Encoding ASCII

$token = & openssl pkeyutl -encrypt -pubin -inkey $pubKey -in secret.txt |
          openssl base64 -A
$token = $token -replace "`r","" -replace "`n",""
$env:WORLDLY_DEV_REQ_TOKEN = $token

# API request
$uri = "https://api-v2.production.higg.org/pic-api/v1/products/search"
$body = '{"from":0,"size":10}'
$headers = @{
    "Content-Type" = "application/json"
    "x-api-key" = $env:WORLDLY_DEVELOPER_API_KEY
    "x-developer-request-token" = $env:WORLDLY_DEV_REQ_TOKEN
}

Invoke-RestMethod -Uri $uri -Method Post -Headers $headers -Body $body | ConvertTo-Json -Depth 5

7. Token Renewal

Tokens expire every 12 hours.
Automate regeneration with a Windows Task Scheduler job that runs the script twice daily.

Quick Reference

Parameter	Example	Notes
Developer API Key	`abcd1234xyz...`	Used in `x-api-key`
Integration API Key	`efgh5678uvw...`	Used inside the encrypted token
Timestamp Format	`2025-10-09T22:14:00Z`	UTC ISO 8601
Token Lifetime	12 hours	Must be refreshed
Public Key File	`/path/to/public.pem` or `C:\Path\To\public.pem`	Must contain `BEGIN PUBLIC KEY` / `END PUBLIC KEY` lines

Summary

Combine your Integration Key and a current UTC timestamp.
Encrypt the string with your Developer Public Key using OpenSSL.
Base64-encode and remove newlines.
Send the token as x-developer-request-token along with your x-api-key.
Regenerate every 12 hours.

Getting Started

Data Dictionaries

Authentication Guide

Worldly Public API Authentication Guide

Overview

Prerequisites

macOS / Linux Instructions

1. Set Environment Variables

Check both values are set correctly:

2. Create the Plaintext Token String

Example content:

3. Encrypt Using Your Developer Public Key

Save the output token to an environment variable:

4. Send an API Request

5. Troubleshooting

6. Example: Full Script (macOS/Linux)

7. Token Renewal

Windows / PowerShell Instructions

1. Set Environment Variables

2. Create the Plaintext String

3. Encrypt and Encode

4. Send API Request

5. Troubleshooting

6. Example: Full PowerShell Script

7. Token Renewal

Quick Reference

Summary

​Worldly Public API Authentication Guide

​Overview

​Prerequisites

​macOS / Linux Instructions

​1. Set Environment Variables

​Check both values are set correctly:

​2. Create the Plaintext Token String

​Example content:

​3. Encrypt Using Your Developer Public Key

​Save the output token to an environment variable:

​4. Send an API Request

​5. Troubleshooting

​6. Example: Full Script (macOS/Linux)

​7. Token Renewal

​Windows / PowerShell Instructions

​1. Set Environment Variables

​2. Create the Plaintext String

​3. Encrypt and Encode

​4. Send API Request

​5. Troubleshooting

​6. Example: Full PowerShell Script

​7. Token Renewal

​Quick Reference

​Summary

Worldly Public API Authentication Guide

Overview

Prerequisites

macOS / Linux Instructions

1. Set Environment Variables

Check both values are set correctly:

2. Create the Plaintext Token String

Example content:

3. Encrypt Using Your Developer Public Key

Save the output token to an environment variable:

4. Send an API Request

5. Troubleshooting

6. Example: Full Script (macOS/Linux)

7. Token Renewal

Windows / PowerShell Instructions

1. Set Environment Variables

2. Create the Plaintext String

3. Encrypt and Encode

4. Send API Request

5. Troubleshooting

6. Example: Full PowerShell Script

7. Token Renewal

Quick Reference

Summary