Docs / How-to guides

Open a server to your API's users

Let the people who use your API connect their own agents by signing in to it, with no Sokie account, in your brand.

Open a server to your API's users, and the people who use your API connect their own agents to it by signing in to your API, or with their own API key. They don't need a Sokie account. Each person's calls use their own access to your API, each answers their own Ask first, and nobody on your team approves their calls.

Each person has to bring their own credential, and Sokie has to tell people apart. On the server's Settings tab, Access links to Sign-in, where you set it up once:

How they sign in: your API's own sign-in (OAuth), or their own API key.
Your sign-in provider: type its address and choose Look it up. A provider that speaks OpenID Connect fills in its sign-in and token addresses itself, and its ID token says who signed in. Otherwise, copy the two addresses from your provider's docs.
Your OAuth app: in your provider, make an OAuth app for Sokie and give it the redirect address the page shows, https://sokie.sh/connect/callback. Paste its client ID and client secret. The secret is kept encrypted in the server's Secrets, never in sokie.json.
Who signed in: without OpenID Connect, name the call that says who signed in, like /v1/me, and choose Sign in to check. You sign in once yourself, which also checks the app and its redirect address work, and then click the fields in the answer that hold each person's id, email and name. For a key, paste one of yours to check instead; it isn't kept.
Save: for a server Sokie keeps the files of, saving deploys it with the new sign-in, and Restore undoes it. For a server linked to a repository, saving opens a pull request there; merge it to go live.

The page writes upstream.auth in the server's sokie.json, so you can also set it there yourself:

"upstream": {
  "auth": {
    "type": "oauth",
    "authorizationUrl": "https://acme.com/oauth/authorize",
    "tokenUrl": "https://acme.com/oauth/token",
    "clientId": "acme-mcp",
    "clientSecret": { "secret": "OAUTH_CLIENT_SECRET" },
    "tokens": "perCaller",
    "identity": { "path": "/v1/me", "id": "id", "email": "email", "name": "name" }
  }
}

id, email and name are dotted paths into the answer, like data.user.id, and identity isn't needed when the scopes include openid. For a key per caller, it's an apiKey with "key": "perCaller"; without identity, a key is known by a fingerprint, so the same key is the same person. Sokie calls path on your API's base URL with the person's own token or key, once when they sign in. If your API answers a key with a 401 or 403, they're told it wasn't accepted and can try again; any other error, or an answer without id, tells them to contact your support. If that call sits outside the base URL, like /oauth/userinfo beside /v1, give url in place of path: its full https address, on your API's own host.

Open it

On the server's Settings tab, the Access card has Open to its API's users. Confirm, and the server redeploys with the new setting. If its users can't sign in yet, the card takes you to Sign-in instead. In a team, opening a server to more people is for owners and admins; a member sees Ask an admin (Ask an admin). Going back to Make private asks nobody.

While it's open, your team connects the same way as everyone else: by signing in to your API.

What they see

Their agent opens a page on sokie.sh in your brand, from Settings › Branding on the workspace. It takes them to your API's sign-in (or asks for their API key), then asks what their agent may do: everything the server allows, or Read only. Then they're back in their agent.

When a call needs their OK, the agent shows a link to sokie.sh/answer/…, where they sign in to your API again and allow it once or refuse it. Their agents page, sokie.sh/agents/<your server>, lists the agents they connected, holds any of them to reading, and disconnects them. It also shows what their agents did in the last 30 days: each call's tool, which agent made it, and how it went (done, allowed or refused by them, not allowed, or an error from your API). Only the tool and the result are kept, never what was in a call.

Which agent called

Every call Sokie makes to your API for one of its users says which of their agents made it, in four headers:

x-sokie-connection: one agent's connection. It stays the same while the agent stays connected, and changes when the agent connects again. Key "stop this agent" on it: answer that agent's calls with an error, and the person's other agents carry on.
x-sokie-client: the agent's name, as the agent gave it. A label, not proof.
x-sokie-client-verified: true when the agent is known by the address of its published details, as Claude and ChatGPT are, and false otherwise.
x-sokie-client-id: that address, such as https://claude.ai/oauth/mcp-oauth-client-metadata, only when verified.

Sokie sets them, after the headers in sokie.json, and no caller can send them. A name outside plain ASCII arrives percent-encoded, as UTF-8. A server deployed before Sokie's runtime 0.3.2 sends none of them until it's redeployed.

Who connected

A server open to its API's users has a Callers tab (press 8). At the top: callers this month, everyone who has connected, how many calls asked first this month and how those went (allowed, refused, or waited too long), and how many callers are blocked. Below, who connected, by their account with your API, with their agents, calls this month, how many of their calls asked first and how many they allowed, and last call, newest first. Search by name, email or your API's id for them. Block stops a caller's agents at once, and they can't connect again until you choose Let back. Every block is in Audit. What's in their calls is never kept.

Put it on your site