Generating an API key
An API key is a credential that lets a program act as you. It never carries more than your own account: the trials you can see, the sites you are restricted to, whether you can export data or read fields flagged as PII. It can carry less — a key can be created read-only, and it can be tied to particular trials — so the system holding it gets only the access it needs. For a narrower slice again, create a dedicated user for the integration with only the trial permissions it needs, and generate the key from that account.
Creating a key
- Open the account menu in the top-right corner of the web app and choose Account settings, then the Account tab.
- Under API keys, click Create key.
- Name. Use the name of the system that will hold it —
Data warehouse sync,REDCap bridge— so you can tell keys apart later. - Expires after. The number of days from now that the key should work for. Leave it blank for a key that never expires. Keys that expire are the safer choice: a key that has to be replaced every 90 or 365 days is one that cannot be forgotten about.
- Access. Choose Read and write or Read only — see below.
- Trials. Leave it on Every trial I can access, or choose Only the trials I choose and tick them — see below.
- Click Create key, then confirm it's you: a key carries all of your access and can be set never to expire, so Trialflare asks you to present your passkey or authenticator code first — and your password as well if you signed in more than a day ago. This is the same confirmation used for signing responses and locking a database.
The key is shown once, in a dialog, with a copy button. Store it in your secrets manager before closing the message — Trialflare does not keep a copy you can read back, and the list of existing keys shows only names, dates and access.
Read-only and read-and-write keys
Read and write lets the key do anything your account can: register participants, edit responses, send messages, change a trial's configuration.
Read only lets the key read and export, and nothing else. Any request that would create, change or delete is refused, whatever your own permissions allow. Choose it for reporting, dashboards, data warehouse syncs and anything else that only needs to look — it means a leaked key cannot alter study data. Building an export is still allowed, since an export only reads; fetching a participant's sign-in link is not, since that link could be used to submit data.
A key's access is fixed when it is created. There is no way to widen or narrow a key afterwards — delete it and create another with the access you want. This is deliberate: the access a key was granted is a matter of record for its whole life, and a key that could be quietly promoted would not be.
Access only ever narrows what your account can do; it never adds anything. A read-and-write key held by an account that cannot register participants still cannot register participants.
Managing keys
Existing keys lists every active key on your account with its name, its access, the trials it is restricted to (if any), when it was created and when it expires. Keys created before access levels existed are marked Full access and behave as read-and-write. Delete a key from there when the integration that used it is retired or the key may have been exposed. Deletion is immediate: the next request made with that key is refused.
Every key stays tied to your account. If your account is disabled by a team manager, every key you created stops working at the same moment. Deleting your account deletes its keys.
Keys in the audit trail
Actions taken with an API key are recorded in the trial and team event logs exactly as if you had taken them in the web app, and the log entry notes which key was used. Anyone reading a trial's Settings → Audit → Logs tab will see the key's name against the event, which is one more reason to name keys after the system that holds them.
Creating and deleting a key are themselves recorded in the team event log. The creation entry carries the key's name, the access and trials it was given, and how you confirmed it was you; the deletion entry carries the same details, so the log says what each key could do and for how long it existed without having to find the entry that created it.
Restricting a key to particular trials
By default a key reaches every trial your account can, including trials you join later. Choosing Only the trials I choose ties it to the trials you tick: every other trial is invisible to it, as though your account were not a member. It sees no participants, responses, documents or event-log entries from them, and listing the team's trials returns only the trials it may reach.
Use it to give a study its own credential. A warehouse sync for one study, or an integration a CRO runs on a single trial, then cannot read the rest of your portfolio even though the person who created the key can.
A restricted key cannot create trials or manage your team, and cannot act on your team's settings or users. Those permissions are held at team level rather than against a trial, and a key that kept them would reach every trial in the team through them — so they are removed along with everything else outside the chosen trials. If your integration needs them, it needs an unrestricted key.
Like access, the trials are fixed when the key is created. To change them, delete the key and create another.
Sites and groups inside a chosen trial come with it, so a key created by a site-restricted account still sees exactly the participants that account sees — no more, and no less.
Keys and two-factor authentication
Your second factor is asked for when you create a key, not when one is used. A key is a bearer credential, and whoever holds it can make requests with it. Treat it as you would a password: never commit it to source control, never put it in a URL, and rotate it if you have any doubt about where it has been.
Because a key cannot present a passkey or an authenticator code, a key cannot create another key. Keys are minted from the web app by a person, and nowhere else. Deleting a key asks for nothing — if you think a key is loose, revoke it straight away.
An account that has neither a passkey nor an authenticator app — a single sign-on account that has added neither — has nothing to present, so it cannot create keys until one is added under Settings → Password & two-factor.
Keys are separate from the Connected applications listed below them in the same settings tab. Those are AI assistants connected through the MCP connector, which sign in through your browser rather than with a key you hold. They use the same two access levels, chosen on the consent screen when you connect them rather than when a key is created. An API key is not a way to connect an assistant — connectors sign in with OAuth.