API Key Guide

Overview

An API key authenticates your requests to WeTrials public data APIs: the Labrador widget and the Labrador API. Each key belongs to your organization, and the API uses it to find your organization's study list and settings.

You create and manage your keys yourself in WeTrials Console.

Table of Contents

1. API Key vs OAuth
2. Creating an API Key
3. Key Restrictions
   • Application restrictions
   • API restrictions
4. Using Your API Key
5. Keeping Your Key Safe
6. Managing Keys
7. Troubleshooting

API Key vs OAuth

Feature	API Key	OAuth 2.0
Use Case	Public data access	Private/user-specific data
Complexity	Simple integration	More complex flow
Data Access	Public clinical trials, studies	Patient data, personal information
Authentication	Single key	Token-based with refresh
Typical Usage	Widgets, public search	Server-to-server, user apps

Creating an API Key

1. Sign in to WeTrials Console and open Developers → API Keys.
2. Click Create API key.
3. Enter a Name that tells you where the key is used, for example Study finder on example.org.
4. Under Key restrictions, choose where the key can be used and which APIs it can call. See Key Restrictions. Restrict key starts selected with no API ticked, and a key saved that way cannot call any API. For the Labrador widget, tick Labrador Study, Learning Center and Support.
5. Click Create, and copy the key shown under Your API key.

You can copy the key again at any time with the copy button in the Your API Keys list.

A key works only in the environment it was created in. Keys created in WeTrials Console work with https://api.wetrials.com; keys created in the development Console, https://console.dev.wetrials.com, work with https://api.dev.wetrials.com.

Key Restrictions

A key without restrictions can be used from anywhere and for every API, and WeTrials Console warns you when you create one. Restrict every key that you put on a website.

Application restrictions

Choose where the key can be used from:

Option	Use it for	A request is accepted when
None	Trying the API out	Always
Websites (HTTP referrers)	Keys in web pages, such as the Labrador widget	The browser's Origin or Referer header names a listed website
IP addresses	Keys used by your servers	It comes from a listed IP address

Websites

Enter one website per line:

https://example.org
https://www.example.org

• Only the hostname is compared. The protocol, port and path are ignored, so https://example.org/find-trials and example.org mean the same site.
• *.example.org allows example.org and all of its subdomains, such as www.example.org and trials.example.org.
• A request with neither an Origin nor a Referer header is refused, so a website-restricted key does not work from a server or from curl. Create a separate key with an IP address restriction for those.
• This restriction stops other websites from using your key in their pages. It does not make the key secret: anyone who opens your page can read the key, and a program outside a browser can send any header it wants.

IP addresses

Enter one IPv4 or IPv6 address, or one CIDR range, per line:

203.0.113.7
198.51.100.0/24
2001:db8::/32

• The address checked is the public IP address your requests come from.
• A line that is not a valid address or range is ignored.

API restrictions

Option	Effect
Don't restrict key	The key can call any API.
Restrict key	The key can call only the APIs you select.

Restrict key is selected when you start, with no API ticked. Tick at least one API, or the key is refused by every endpoint.

The APIs used by the Labrador widget and the Labrador API:

API	What it covers
Labrador Study	Study search, facet values, study details and the widget configuration
Learning Center	Learning Center categories and articles
Support	Patient support programs

The Labrador widget uses all three. If its key is restricted to fewer, the matching part of the widget cannot load its content. The endpoints behind each API are listed under Permissions.

Using Your API Key

With the Labrador widget

Labrador({
  shadowRoot: document.getElementById('study-finder'),
  shadowModalRoot: document.getElementById('modal-root'),
  env: 'production', // or 'development'
  orgId: 'your-org-id',
  apiKey: 'your-api-key',
});

See the Labrador Setup Guide for the full setup.

Direct API calls

Send the key as the apiKey query parameter:

const response = await fetch(`https://api.wetrials.com/v2/labrador/study?apiKey=${apiKey}&query=glioblastoma`);
const { hits, nbHits } = await response.json();

The key is read from the query string only; Authorization and x-api-key headers are ignored. Every endpoint is described in the Labrador API Reference.

Keeping Your Key Safe

• A key in a web page is public. The widget sends the key from your visitor's browser, so anyone can find it in your page. Give such a key a website restriction.

• A key on a server is private. Keep it out of source control, for example in an environment variable, and give it an IP address restriction.

  # .env (add to .gitignore)
  WETRIALS_API_KEY=your-api-key

• Use one key per website or application, so that you can restrict, replace or turn off each one on its own.

Managing Keys

The Your API Keys list in Developers → API Keys shows each key's status and when it was last used. From a key's Actions menu you can:

• Edit the key: rename it, change its restrictions, or set its Status to Inactive. An inactive key is refused with 401 Invalid API key until you make it Active again.
• Delete the key. Requests with a deleted key are refused with 401 Invalid API key, and a deleted key cannot be restored.

To replace a key — for example, after it leaked from a server — create a new key with the same restrictions, switch your website or application to it, and then make the old key Inactive or delete it.

Troubleshooting

Error	Cause	What to do
401 API key is required	The request has no apiKey query parameter, or an empty one.	Add apiKey to the query string. Headers are not read.
401 Invalid API key	The key is wrong, deleted or inactive, or apiKey appears more than once in the URL.	Check that the key is listed and Active in WeTrials Console, and that you are calling the API of the environment the key was created in.
403 API access denied	The key's API restrictions leave out this API — or no API was ticked under Restrict key.	Edit the key and select the API, or choose Don't restrict key.
403 Origin required	A website-restricted key was used outside a browser.	Use a key with an IP address restriction for calls from servers.
403 Domain not allowed	The page's hostname is not on the key's website list.	Add the hostname shown in the browser's address bar. For subdomains, add *.example.org.
403 IP not allowed	The request did not come from an address on the key's list.	Add your server's public IP address, or a CIDR range that contains it.

All error responses are listed under Errors in the API Reference.

Getting Help

Email platform@wetrials.com with your organization name and the full error response. Never send your API key by email.

---

Last Updated: October 2026 Maintained By: WeTrials Platform Team