User Provisioning

Overview

If you are building your own product on Junis, your users should each get their own Junis account — so their conversations, history, and memory stay separate — without anyone having to sign up for Junis. User Provisioning does exactly that: you create an account for each of your users, run everything on their behalf, and pay for all of it from one place. You never share your API key with your users, and they never see Junis.

The lifecycle

Create an account for each of your users

One call with their email. Idempotent, so you can call it every login.

Connect the accounts they need

Push API keys straight in, or hand the person a connect link for anything that needs their sign-in (Gmail, Slack). Your agents then act as that user.

Run chats as that user

Add on_behalf_of to your normal calls. Sessions and memory belong to them.

Show them their history

The same parameter works on the session read endpoints.

Delete their data when they leave

Purge their conversations permanently, so you can honour your own deletion promise.

Billing never moves. Subscription checks and credit charges always stay with the user behind your API key, no matter whose name a call runs under. Your users do not need a Junis subscription — or a Junis account they ever log into.

Provisioned accounts do not receive the signup credit bonus and have no memory profile until the person actually signs in with Google themselves. If they ever do, their Google account links to the one you created and their membership activates — nothing is lost or duplicated.

Getting a key

Create the key from Dashboard → API Keys → New Key and tick “Connect users from my own app” before generating it. That checkbox is what turns an ordinary key into a provisioning key.

Checkbox	Scopes granted
Unchecked (default)	The 8 standard scopes — `orchestrator:`, `sessions:`, `agents:`, `content:`
Checked	The 8 standard scopes plus `users:provision`, `users:delegate`, `sessions:delete` and `users:credentials`

Scope	What it lets you do
`users:provision`	Create accounts for your users
`users:delegate`	Run and read as one of those users
`sessions:delete`	Delete their conversations
`users:credentials`	Store API credentials on their behalf (write-only), issue/revoke connect links, and read connect status

Scopes are frozen into a key when it is created. If you already have a provisioning key from before users:credentials existed, generate a new one to get it — existing keys are not upgraded.

Only organization owners and admins can open that page, which is also the requirement for using these scopes — so a key created there is always eligible. Provisioning keys are named provisioning-key-… and carry a User provisioning label in the key list, so you can tell them apart later.

This key can create accounts in your organization, run chats as its members, and delete conversations. Keep it on your server — never ship it in a browser, a mobile app, or a public repository.

Endpoint

POST https://api.junis.ai/api/external/management/users

Authentication

Include your API key in the X-API-Key header:

X-API-Key: jns_live_YOUR_API_KEY_HERE

Request Parameters

Parameter	Type	Required	Description
`email`	string	Yes	Email of the user to provision (normalized to lowercase)
`name`	string	No	Display name (defaults to the email local part)
`organization_id`	string	Yes	Must match the organization your API key resolves to

Example Request

curl -X POST https://api.junis.ai/api/external/management/users \
  -H "X-API-Key: jns_live_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "name": "Alice",
    "organization_id": "org-uuid"
  }'

Response

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "alice@example.com",
  "created": true,
  "delegable": true,
  "membership_status": "pending"
}

Field	Type	Description
`user_id`	string	Junis user ID — usable as `on_behalf_of` in Chat Completions
`email`	string	Normalized email
`created`	boolean	`true` if a new account was created, `false` if it already existed
`delegable`	boolean	`true` if you can act on behalf of this account (see below)
`membership_status`	string	`pending` (awaiting first login) or `active`

When the Email Belongs to an Existing Junis User

If the email already belongs to a real Junis account (someone who has signed in themselves), the account is not attached to your organization and cannot be delegated:

{
  "email": "existing-user@example.com",
  "created": false,
  "delegable": false
}

Only the email is echoed back — no user ID or membership information is returned. Handle this case in your integration: invite the user to your organization from the dashboard instead, or skip Junis-linked features for that user.

Behavior

Create-or-get user

If a user with the email already exists, it is returned unchanged (created: false). Otherwise a new account is created with google_id = NULL — no signup bonus, no memory profile (both happen on the real first login).

Ensure pending membership

If the organization has no membership row for this email, a pending invite with the member role is created — identical to inviting the user from the dashboard.

First Google login links everything

When the user signs in with Google using that email, the account is linked to their Google identity, the pending membership is activated, and the invited organization becomes their current organization.

The endpoint is idempotent — calling it repeatedly for the same email returns the same user and membership state.

Errors

Status	Code	Description
`403`	`insufficient_scopes`	API key lacks the `users:provision` scope
`403`	—	Key’s organization does not match `organization_id`, or the backing user is not an org admin/owner
`422`	—	Invalid email address

Storing API Credentials for a User

Most useful automations need to call something on the person’s behalf — their Notion, their Google Sheets, their store. Those calls need their key, not yours. Push the credential into their account once, and every agent that runs for them uses it automatically. They never paste a key into a chat, and the key never reaches the model.

Endpoints

GET    https://api.junis.ai/api/external/management/users/{user_id}/secrets
PUT    https://api.junis.ai/api/external/management/users/{user_id}/secrets/{NAME}
DELETE https://api.junis.ai/api/external/management/users/{user_id}/secrets/{NAME}

Requires the users:credentials scope and an owner/admin key.

Store or rotate

PUT is idempotent — the same call creates a credential the first time and rotates it every time after.

curl -X PUT \
  "https://api.junis.ai/api/external/management/users/USER_ID/secrets/NOTION_TOKEN" \
  -H "X-API-Key: jns_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "secret_xxx", "description": "Customer Notion token" }'

{ "success": true, "user_id": "USER_ID", "name": "NOTION_TOKEN", "scope": "private" }

Check what they have

Returns names only — never values. Use it to work out what is still missing and prompt for it in your own onboarding UI.

curl "https://api.junis.ai/api/external/management/users/USER_ID/secrets" \
  -H "X-API-Key: jns_live_YOUR_KEY"

{
  "user_id": "USER_ID",
  "secrets": [
    {
      "id": 12,
      "name": "NOTION_TOKEN",
      "description": "Customer Notion token",
      "created_at": "2026-08-21T04:10:00+00:00",
      "updated_at": "2026-08-21T04:10:00+00:00"
    }
  ]
}

Delete

Do this when the person leaves, alongside deleting their conversations.

curl -X DELETE \
  "https://api.junis.ai/api/external/management/users/USER_ID/secrets/NOTION_TOKEN" \
  -H "X-API-Key: jns_live_YOUR_KEY"

Stored values can never be read back. There is no endpoint, on any key, that returns a credential’s value — listing gives you names only. If your key leaks, the credentials already stored with it cannot be pulled out.

Only accounts you provisioned. If the email already belonged to a real Junis user (delegable: false), this returns 403. Nobody — not even an organization owner — can write into a real person’s private vault. That rule is what makes the vault trustworthy, so it has no exceptions.

Rules

Rule	Value
Name format	Uppercase letters, digits, underscore. Must start with a letter — `NOTION_TOKEN`
Value size	8 KB max (fits PEM keys and service-account JSON)
Count	200 credentials per user, per organization
Rotation	Always allowed, even at the count limit
Organizations	Separate vaults — the same person can hold a different key in each org

Errors

Status	Code	Description
`400`	—	Invalid name — must be uppercase letters, digits, underscore
`400`	—	The 200-credential limit is reached (rotating an existing name still works)
`403`	`insufficient_scopes`	Key lacks `users:credentials`
`403`	—	Target is a real account, not one your organization provisioned
`403`	—	Target was provisioned by a different organization
`404`	—	User not found, or (on `DELETE`) no credential with that name
`422`	—	Body validation failed — empty `value`, or a value longer than 8 KB

Listing Your Provisioned Users

Reconcile against your own database, or build an internal admin view. Only accounts your organization provisioned appear — never real Junis users.

curl "https://api.junis.ai/api/external/management/users?limit=50&offset=0" \
  -H "X-API-Key: jns_live_YOUR_KEY"

{
  "users": [
    { "user_id": "usr_1", "email": "customer@example.com", "name": "Customer", "created_at": "2026-08-21T04:00:00+00:00" }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Requires users:provision.

Connect Links — let the person connect what the squad needs

An API key you can push in directly (§ above). Gmail, Slack, Google Calendar and other OAuth apps you cannot — those credentials only exist after the person clicks “Allow” on the provider’s own consent screen. And even for plain API keys, it is better when the person’s key never passes through your servers. A connect link solves both with one flow: you request a link for a squad, open it in a webview, and the person connects (or disconnects) everything on one page. OAuth redirects, key entry and encryption are handled for you — your app needs no callback page and no OAuth code. The page carries no branding other than what the person is connecting to.

Ask for a link

One call with the squad’s agent_id. The page shows only what that squad needs.

Open it in a webview

The person connects each item. OAuth apps redirect out and come back automatically.

They return to your app

Via your return_url — even if they only connected some items.

What the page shows

Pass the squad’s root agent (agent_id, from GET /management/agents). The page is built from what is configured on that agent and its sub-agents:

Section	Items
Accounts	Personal Composio integrations linked to the squad (`connection_type: "personal"`) — Gmail, Notion, …
Credentials	MCP platforms linked to the squad that need a personal credential. Platforms your organization already provides a key for are not shown
API keys	Personal keys the squad’s instructions reference as `{cred:private:NAME}`

If the squad changes later, existing links follow the new configuration.

Check what is needed — and what is done

Use the same endpoint before issuing a link (is there anything to connect?) and after (did they finish?). It is generated by the same code as the page, so what you see is what the person sees.

curl "https://api.junis.ai/api/external/management/users/USER_ID/connect-status?agent_id=AGENT_ID" \
  -H "X-API-Key: jns_live_YOUR_KEY"

{
  "user_id": "USER_ID",
  "agent_id": "AGENT_ID",
  "all_connected": false,
  "items": [
    { "kind": "composio", "id": "3f9c…", "name": "Gmail", "auth_scheme": "OAUTH2",
      "connected": false, "fields": [] },
    { "kind": "mcp", "id": "notion-mcp", "name": "Notion", "connected": true,
      "fields": [ { "name": "NOTION_TOKEN", "type": "text", "required": true } ] },
    { "kind": "secret", "id": "HUNTER_API_KEY", "name": "HUNTER_API_KEY", "connected": false,
      "description": "Used by hunter_api", "fields": [ { "name": "value", "required": true } ] }
  ],
  "skipped": [
    { "kind": "mcp", "id": "replicate-global", "name": "Replicate", "reason": "provided_by_system" }
  ]
}

skipped explains what is not on the page and why: provided_by_organization / provided_by_system (already works without the person doing anything), or no_credential_schema (the platform does not declare which values it needs — the squad’s admin adds that in the platform settings and the item appears), or too_many_items (more than 20 of one kind; trim the squad). An item with no declared fields stays hidden even when already connected: the page cannot store that value, so it does not offer to remove it either — that would be a one-way door. Items we provision automatically never appear at all, since there is nothing for the person to enter. Stored values are never returned — only connected and field names.

Request a link

curl -X POST \
  "https://api.junis.ai/api/external/management/users/USER_ID/connect-sessions" \
  -H "X-API-Key: jns_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "AGENT_ID",
        "return_url": "myapp://connect-done",
        "ttl_minutes": 30
      }'

{
  "url": "https://junis.ai/connect/xNq7...",
  "expires_at": "2026-09-07T05:00:00+00:00",
  "user_id": "USER_ID",
  "agent_id": "AGENT_ID",
  "items": { "composio": [], "mcp": [] }
}

Field	Notes
`agent_id`	The squad’s root agent. Recommended.
`composio` / `mcp`	Explicit mode: list catalog ids yourself (`GET /management/composio/integrations` → `id`, `GET /management/mcp-platforms` → `platform_id`). Cannot be combined with `agent_id` (`400`). Kept for compatibility
`return_url`	Optional. `https://…` or a custom app scheme like `myapp://done`. `http://` and `javascript:`/`data:`/`file:` are rejected
`ttl_minutes`	Default `30`, max `1440`

Requires users:credentials, and the target must be an account you provisioned. If the squad has nothing for the person to connect, the request returns 400 with the same skipped list as connect-status.

The token in url is shown once. Only its hash is stored, so the link cannot be looked up again — request a new one instead. Treat the URL like a password: it is the only thing standing between a stranger and that user’s connect page.

Open it in a webview

Fetch the link at the moment the person taps your “Connect” button, then open it. Do not pre-generate links — a 30 minute lifetime is what keeps a leaked URL harmless.

[ Connect accounts ]  →  POST …/connect-sessions  →  open url in webview

Item	What the person sees
Gmail, Slack (OAuth)	Connect → provider consent → back to the page, marked connected
Notion, Airtable (API key)	A key field → Save
MCP credentials	One field per value the platform declares, by name → Save
API keys	A key field → Save
Anything connected	Disconnect

The page shows All set when everything is connected, and a button back to your app whenever you set return_url — including when only some items are done, so the person can come back and finish later.

Revoke links

When a person leaves your app, or you suspect a link leaked, invalidate every live link for that account at once. Idempotent.

curl -X DELETE \
  "https://api.junis.ai/api/external/management/users/USER_ID/connect-sessions" \
  -H "X-API-Key: jns_live_YOUR_KEY"

{ "user_id": "USER_ID", "revoked": 1 }

What the page can and cannot do

The link grants exactly one thing: connecting and disconnecting that one user’s items for that one squad. It cannot read data, cannot reach other users, cannot touch items outside the squad, and cannot reveal any stored value. The page never shows your organization, the user’s id, or their email.

Expired, revoked and non-existent links all return the same response — a link cannot be probed for validity.
Reusable until it expires, because an OAuth round trip has to come back to it.
Connecting or disconnecting refreshes that user’s agent tools immediately.

Errors

Status	Code	Description
`400`	—	`agent_id` combined with `composio`/`mcp`, nothing to connect (see `skipped`), more than 20 explicit items, bad `return_url`, or an unknown toolkit id
`403`	`insufficient_scopes`	Key lacks `users:credentials`
`403`	—	Target is a real account, or was provisioned by another organization
`404`	—	User not found, or `agent_id` is not an active agent of your organization (global agents are accepted)

Using a Stored Credential in an Agent

Reference the credential by name in the agent’s instruction. Junis substitutes the calling user’s own value at request time and sends it as an HTTP header — it never enters the prompt, the model’s context, or the conversation log.

[CUSTOM_API_CONFIG]
{
  "apis": [{
    "name": "notion",
    "endpoint": "https://api.notion.com/v1/search",
    "method": "POST",
    "api_key_header": "Authorization",
    "api_key": "Bearer {cred:private:NOTION_TOKEN}",
    "headers": { "Notion-Version": "2022-06-28" }
  }]
}
[/CUSTOM_API_CONFIG]

Syntax	Resolves to
`{cred:private:NAME}`	The calling user’s own credential
`{cred:NAME}`	A single organization-wide credential shared by everyone

The two never substitute for each other. If a user has no credential with that name, the call is not sent — the tool returns an error naming what is missing, instead of quietly falling back to an organization key.

The config is read from the instruction of the agent that owns the custom_api_call tool — not from the orchestrator. If a sub-agent makes the call, the block belongs in that sub-agent’s instruction. Giving one dedicated agent the tool and the config keeps it out of your orchestrator’s context on every turn.

Writing it into an agent

Owner/admin only, with a user-level key carrying agents:manage. Read the current instruction, append your block, and write the whole thing back — instruction is replaced wholesale, not appended to.

# 1. Read the current instruction
curl "https://api.junis.ai/api/external/management/agents/AGENT_ID" \
  -H "X-API-Key: jns_user_YOUR_KEY"

# 2. Write back the combined instruction (and the tool, if not already assigned)
curl -X PUT "https://api.junis.ai/api/external/management/agents/AGENT_ID" \
  -H "X-API-Key: jns_user_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "instruction": "<existing instruction>\n\n[CUSTOM_API_CONFIG]...[/CUSTOM_API_CONFIG]",
        "tools": ["custom_api_call"]
      }'

instruction and tools are both replaced in full. Fetch, merge, then write — and have only one process doing it, or two concurrent writers will overwrite each other.

An organization-level provisioning key cannot do this — it does not carry agents:manage. Use a user-level key created by an owner or admin from Settings → API Keys. The two keys have different jobs: the provisioning key manages accounts and their credentials, the user-level key manages agents.

Users Managing Their Own Credentials

If the person signs into Junis themselves, they manage their own credentials — you do not need to push anything.

In the app: Team → MCP & Keys → My Keys. Open to every member, including those with the MEMBER role.
Over the API: with their own user-level key carrying secrets:manage.

GET    https://api.junis.ai/api/external/management/me/secrets
PUT    https://api.junis.ai/api/external/management/me/secrets/{NAME}
DELETE https://api.junis.ai/api/external/management/me/secrets/{NAME}

curl -X PUT "https://api.junis.ai/api/external/management/me/secrets/NOTION_TOKEN" \
  -H "X-API-Key: jns_user_THEIR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "value": "secret_xxx" }'

These endpoints accept user-level keys only. An organization-level key is rejected with 403, because such a key resolves to whoever created it — accepting it would let every holder of that key edit that person’s private vault.

Same rules as above: names only on read, 8 KB per value, 200 per organization, and no way to read a value back.

Running as a Provisioned User

Take the user_id from the provisioning response and pass it as on_behalf_of. It works on both invocation endpoints and needs the users:delegate scope:

Endpoint	Use it for
`POST /v1/chat/completions`	Your main assistant — routed through the orchestrator
`POST /agents/{id}/completions`	A single agent, called directly

{
  "model": "junis",
  "messages": [{ "role": "user", "content": "How did I sleep last week?" }],
  "on_behalf_of": "USER_ID"
}

Sessions, messages, and memory belong to that user. Subscription checks and credit charges stay with your API key’s own user. Delegation works before their first login, so you can start using an account the moment you create it.

Keeping one-off calls out of their history

Both endpoints accept session_hidden: true. Use it for calls that are part of your product’s machinery rather than a conversation the user should see later — scoring, classification, background analysis:

{
  "message": "Classify this entry",
  "on_behalf_of": "USER_ID",
  "session_hidden": true
}

Hidden sessions still belong to the user and still bill to you; they are simply left out when you list a user’s conversations with include_hidden=false.

Showing a User Their History

The same on_behalf_of parameter works on the session read endpoints, so you can build a history view inside your own product:

# Their conversations, newest first
curl "https://api.junis.ai/api/external/sessions?on_behalf_of=USER_ID&include_hidden=false" \
  -H "X-API-Key: jns_live_YOUR_KEY"

# One conversation, in full
curl "https://api.junis.ai/api/external/sessions/SESSION_ID/messages?on_behalf_of=USER_ID" \
  -H "X-API-Key: jns_live_YOUR_KEY"

# Is a reply still being generated?
curl "https://api.junis.ai/api/external/sessions/SESSION_ID/status?on_behalf_of=USER_ID" \
  -H "X-API-Key: jns_live_YOUR_KEY"

include_hidden=false leaves out the one-off calls you marked with session_hidden, so the list matches what your user would expect to see. It defaults to true. Omit on_behalf_of entirely and you get your own key’s sessions, exactly as before.

Reading is narrower than running. On these endpoints on_behalf_of only accepts accounts your organization provisioned. Chat completions also let you run as a real member of your organization, but reading or deleting their conversations never works — a provisioning key can’t pull a real person’s chat history.

Deleting a User’s Data

When someone deletes their account in your product, delete their Junis conversations too. This is what lets you honour a “we delete everything” promise. Requires the sessions:delete scope, granted by the same checkbox.

curl -X DELETE \
  "https://api.junis.ai/api/external/sessions/SESSION_ID?on_behalf_of=USER_ID" \
  -H "X-API-Key: jns_live_YOUR_KEY"

{ "session_id": "abc123", "deleted": true }

The session, its messages, and its stored state are removed permanently — there is no recovery. To purge a user completely, list their sessions with include_hidden=true (the default, so you catch the hidden ones too) and delete each one. Every deletion is recorded in your organization’s audit log with who deleted it, whose session it was, and whether the call was delegated.

Delegation errors

Status	Code	Description
`403`	`insufficient_scopes`	Key lacks `users:delegate` (read) or `sessions:delete` (delete)
`403`	`delegation_target_not_found`	`on_behalf_of` user does not exist or is inactive
`403`	`delegation_target_not_member`	Target is not an active or pending member of your organization
`403`	`delegation_target_not_provisioned`	Target is a real account, not one your organization provisioned
`404`	—	Session does not exist, or does not belong to the target user

​Overview

​The lifecycle

​Getting a key

​Endpoint

​Authentication

​Request Parameters

​Example Request

​Response

​When the Email Belongs to an Existing Junis User

​Behavior

​Errors

​Storing API Credentials for a User

​Endpoints

​Store or rotate

​Check what they have

​Delete

​Rules

​Errors

​Listing Your Provisioned Users

​Connect Links — let the person connect what the squad needs

​What the page shows

​Check what is needed — and what is done

​Request a link

​Open it in a webview

​Revoke links

​What the page can and cannot do

​Errors

​Using a Stored Credential in an Agent

​Writing it into an agent

​Users Managing Their Own Credentials

​Running as a Provisioned User

​Keeping one-off calls out of their history

​Showing a User Their History

​Deleting a User’s Data

​Delegation errors

Overview

The lifecycle

Getting a key

Endpoint

Authentication

Request Parameters

Example Request

Response

When the Email Belongs to an Existing Junis User

Behavior

Errors

Storing API Credentials for a User

Endpoints

Store or rotate

Check what they have

Delete

Rules

Errors

Listing Your Provisioned Users

Connect Links — let the person connect what the squad needs

What the page shows

Check what is needed — and what is done

Request a link

Open it in a webview

Revoke links

What the page can and cannot do

Errors

Using a Stored Credential in an Agent

Writing it into an agent

Users Managing Their Own Credentials

Running as a Provisioned User

Keeping one-off calls out of their history

Showing a User Their History

Deleting a User’s Data

Delegation errors