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.

What the server needs

Each person has to bring their own credential, and Sokie has to tell people apart. In sokie.json, upstream.auth is one of:

OAuth with tokens per caller: "type": "oauth" with "tokens": "perCaller". Sokie learns who signed in from an OpenID Connect ID token when the scopes include openid. Without one, add identity: the call that says who signed in, and which field of its answer holds their id.
A key per caller: an apiKey with "key": "perCaller". With identity, Sokie names the key's holder; without it, a key is known by a fingerprint, so the same key is the same person.

"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. Sokie calls path on your API's base URL with the person's own token or key, once when they sign in.

In your API's OAuth provider, make an OAuth app (a client) for Sokie, and give it the redirect address https://sokie.sh/connect/callback. Note its client ID and client secret.
On the server's Secrets tab, add the client secret as OAUTH_CLIENT_SECRET, or the name clientSecret gives.
Set upstream.auth in sokie.json as above: the provider's authorization and token addresses, the client ID, "tokens": "perCaller", and identity unless the scopes include openid.
Deploy: push to the linked repository, run sokie deploy, or for a server without one, sokie edit and save. Edit locally covers both.

Then open the server, below. For a key per caller, only steps 3 and 4 apply.

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 what's live can't tell people apart, the card says what sokie.json needs 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.

Who connected

A server open to its API's users has a Callers tab (press 8): who connected, by their account with your API, with their agents, calls this month 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