How clients sign in

Two separate questions decide every call: may this client call the server, and how does the server sign in to your API? Sokie answers the first with OAuth, and the second with what sokie.json says.

Private servers

A private server answers only calls that carry a Sokie token. MCP clients get one with OAuth 2.1, the way the MCP spec describes, so nobody copies a token by hand:

1. The client calls the server without a token, and the server says where to sign in.
2. The client registers itself with Sokie and opens Sokie in your browser.
3. Sokie asks whether to connect the client to the server. You choose Allow or Deny.
4. The client gets a token, and calls the server with it.

Sokie asks every time a client connects, even one you've approved before. A token lasts 15 minutes, and the client renews it by itself for as long as it keeps being used, up to 90 days between uses. Today only a server's owner can approve a client, because teams aren't built yet.

Settings › Connected clients in the app lists every client you've approved. Disconnect one and it can't renew its access, so it's cut off within 15 minutes.

Public servers

A public server answers anyone with its address, with no sign-in. Make one with sokie deploy --create --public, for an API that's public anyway, or switch a server later. While a server is public, clients that signed in to it can't renew their access; they can again once it's private.

A paused server turns every call away. Its clients stay connected, and can renew their access once it's resumed.

Your API's credentials

What a server sends to your API is set by upstream.auth in sokie.json:

• none: the API needs no credentials.
• One key for everyone: an apiKey whose key is a secret, like {"secret": "PETSTORE_KEY"}. Every call uses the owner's key. See Add secrets.
• Each caller's own key: an apiKey with "key": "perCaller". Each person who connects brings their own, and every call uses the key of whoever made it. sokie init chooses this for any key the spec asks for.
• OAuth to the API: "type": "oauth", with the API's endpoints and an OAuth client of your own. "tokens": "perCaller" has each person sign in to the API; "shared" uses one sign-in, the owner's, for everyone. If the API stops accepting a shared sign-in, every call that needs it fails until someone signs in again on the server's connect page, and Sokie emails the workspace's owner a link to it, once each time a sign-in breaks.

A server that uses each caller's own key or sign-in must be private: Sokie can only send a caller's key when it knows who the caller is.

When a caller brings their own key

The first call that needs a key stops, and the client shows a link to Sokie instead. The page asks for the key; once it's saved, the call works when it's run again. Sokie keeps the key encrypted, sends it only on that person's own calls, and never shows it again. If the API refuses it, the next call sends them back to the page to save a new one.

For an API that uses OAuth, the same page has the person sign in to the API instead.

Locally, sokie dev takes the caller's key from SOKIE_CALLER_KEY in .sokie/dev.env, and an OAuth token from SOKIE_OAUTH_TOKEN.

The CLI

sokie login signs the CLI in through the same Sokie sign-in, as you. A CLI sign-in lasts 30 days, or until it goes 7 days unused. Change both under Settings › CLI sign-ins in the app, or shorten them with sokie config.