API keys

Create a Juno API key yourself, in the app or over the account access API, and use it on REST, MCP, and A2A.

5 topics5 min read

API keys are self-service. Any member of a Juno organisation can create one in the app under Settings, then Developer. One key authenticates REST, MCP, and A2A when it carries the permissions those calls need.

There is also an account access API for clients that have no browser to send a person to. It lives under /v1/access and walks through email verification, two-step verification, and workspace selection before it will issue a key.

Create a key in the Juno app Open Settings, then Developer, and select Create key. Or let people connect your app Use OAuth when the workspace belongs to someone else and they should approve the connection.

What a key is

Every key is scoped to one organisation and one API data environment. The jsk_test_ and jsk_live_ prefixes identify that data environment. They are not the study's Test mode and Live mode, which are controlled separately through the study lifecycle.

jsk_live_… jsk_test_…

Key environments are not study modes A key's jsk_test_ or jsk_live_ prefix selects the API data environment. This is separate from a study's Test mode or Live mode: the study lifecycle is controlled by the mode field and the Go live action.

Create a key

In the Juno app, open Settings, then Developer, and select Create key. Give it a name, choose its scopes, choose the test or live data environment, and choose an expiry. Owners and admins see every key in the organisation. Other members see and revoke only their own.

The secret is shown once Copy the key into your secret store straight away. Juno keeps only a hash of it, so a lost secret cannot be recovered. Revoke the key and create another, or use Replace key on the account access API to swap it in one step.

The account access API does the same thing without a browser. Each step returns next_action, telling you what the transaction needs before it will go further.

1 POST /v1/access/transactions. Generate your own bearer proof, 'jmg_' followed by 32 random bytes in base64url, and start the transaction with an email address and your client's name. Keep the proof secret and reuse it for every later call.
2 POST /v1/access/verify-email. Juno emails a token. Submit it. An email address on its own grants nothing.
3 POST /v1/access/mfa/verify. Request a two-step verification challenge by TOTP, SMS, or email, then submit the code.
4 POST /v1/access/workspace. List the workspaces this identity can use and select one, accept an invitation to one, or create a starter workspace.
5 POST /v1/access/keys. Issue the key. Name it, list its scopes, and choose test or live and an expiry of 30, 90, 180, or 365 days, or none. Idempotency-Key is required and must be a UUID; replaying it returns the key's details with a null secret, not a second key.

// Generate your own proof first: "jmg_" + base64url(32 random bytes).
// Keep it secret and send it on every call in this transaction.
curl -X POST https://api.heyjuno.co/v1/access/transactions \
  -H "Authorization: Bearer $JUNO_ACCESS_PROOF" \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "client_name": "Acme Research Copilot" }'

{
  "transaction_id": "0b6a2f3e-9d41-4e6b-8a3f-2f6c1d9e4b7a",
  "client_name": "Acme Research Copilot",
  "state": "awaiting_email",
  "next_action": "verify_email",
  "expires_at": "2026-09-18T01:20:00Z"
}

Scopes

Every key carries a set of permissions, called scopes. Grant only what the integration needs. Seven scopes cover the whole surface:

studies:read: Read studies, study jobs, and simulations.
studies:write: Create and update studies, run a simulation, and change technical collection states. Go live needs its own scope.
studies:golive: Set study mode to 'live'. This performs Go live.
links:read: Read the invite link for a study.
links:write: Create a participant link that carries context about the people it is for.
export:read: List and read participant interviews, and request and download exports.
agent:run: Send agent-to-agent messages over A2A. API keys only. An OAuth connection cannot be granted this permission.

Using a key

Send the key as a bearer token on every request:

Authorization: Bearer jsk_live_…

Confirm what the key resolves to before you build against it. The whoami call returns the organisation and its name, the data environment, the granted scopes, and the key's id, name, and expiry.

curl https://api.heyjuno.co/v1/api/me \
  -H "Authorization: Bearer $JUNO_API_KEY"

See the full REST reference Every endpoint, parameter, and response shape, rendered live from the OpenAPI spec.

Rate limits

Limits are counted against the credential, not your IP address, and they are split by cost. Reads get 120 requests a minute. Writes get 20 a minute. Over the limit you get 429 with a Retry-After header saying how many seconds to wait.

The organisation has its own ceiling on top of that: 600 reads and 60 writes a minute across all of its credentials. Minting more keys does not buy more throughput.

Previous Build with Juno Next OAuth