API tokens

An API token is a bearer credential for triggering loops outside the UI. Tokens are minted from the organization’s settings, scoped to one or all loops in the org, and revocable at any time.

This page covers what a token carries, how scopes work, and how to use one against the trigger endpoint.

What’s on a token

Field	Description
`name`	A label you set at creation. Shown in the tokens list — make it descriptive (e.g. “Production runner”).
`prefix`	The first few characters of the token, kept in the clear so you can identify a token at a glance.
`lastFour`	The last four characters of the token. The rest is hashed and never recoverable.
`scopes`	What the token is allowed to do. See the scopes table below.
`lastUsedAt`	When the token was last used. Useful for spotting unused tokens you can revoke.
`revokedAt`	When the token was revoked, if ever. Revoked tokens stay in the list (struck through) for audit.

The full token string is shown once, when you create it. The platform never stores the original value, so if you lose it you’ll have to mint a new one — there is no recovery flow.

Scopes

Scope	Description
`loop:run`	Trigger any loop in the organization.
`loop:run:<loopId>`	Trigger only the named loop. Useful for keys you share with a single external system.

Pick All loops at creation for general-purpose keys, and One loop for keys you’ll hand to a specific integration so a compromise can’t reach the rest of the org.

A token never crosses organization boundaries — even with the right URL, a token from one org can’t trigger another org’s loops.

Create a token

From Settings → API tokens, click Create token. The dialog asks for:

A name.
A scope — “All loops” or “One loop”. If you pick “One loop,” a second dropdown lets you select which.

After you click Create, the dialog renders the full token string and a Copy button. Store the token somewhere durable before closing the dialog — once it’s gone, it’s gone.

Use a token

POST to the loop’s trigger URL with the token as a Bearer credential:


curl -X POST https://api.ollie.health/loop/$ORG_ID/$LOOP_ID \
  -H "Authorization: Bearer $LOOPS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "patientId": "abc", "phoneNumber": "+15551234567" }'
 
# → { "runId": "run_…", "workflowInstanceId": "…" }

The body of the POST becomes event.body on the run. The response gives you back a runId you can use to find the run in the UI. See Events and triggers for the full request shape.

Runs triggered by a token are tagged with the token (not a user) in the runs list, so you can trace activity back to the integration that initiated it.

Revoke a token

From the tokens list, click the trash icon on a token’s row. Revocation is immediate: the next request that presents the token fails authentication. The row stays in the list with a strike-through so the audit history is intact.

You can’t undo a revoke — to restore access, mint a new token.

Examples

One token per integration

Mint a separately-named token per external system that calls your loops:

Token name	Scope
`EHR webhook`	`loop:run:loop_intake`
`Daily cron`	`loop:run:loop_daily_summary`
`Production runner`	`loop:run` (all loops)

When a third-party system rotates credentials or is decommissioned, you revoke one token without touching the others.

Rotate a production token

To rotate, create the new token first, deploy it to the consumer, verify a trigger lands, then revoke the old token. Tokens can overlap — there’s no limit on how many active tokens an org can hold.