Authentication

Every call but the OpenAPI document needs a key. The API and the MCP server take the same keys. The MCP server also takes a sign-in: Claude, Claude Desktop and ChatGPT connect that way, with no key to copy (see Sign in for assistants). To set up an assistant, see Connect an assistant.

Make a key

Keys are made on the portal's API keys page. Any account can make one, the Free plan included. Give each integration its own key, named for what it does, so you can revoke one without touching the others.

A key is shown once, when it is made. Copy it then; the portal keeps only a hash.

Send it

Put the key in the Authorization header of every request:

Authorization: Bearer <key>

Without a live key the answer is 401, with a WWW-Authenticate: Bearer realm="NestSolver API" header and one problem in the body:

{ "errors": [{ "field": null, "message": "Send a live API key as \"Authorization: Bearer <key>\".", "upgrade": null }] }

What a key reaches

A key acts in the workspace it was made in, under that workspace's tier. It can do what a member of the workspace can do on the web, within the same caps, with two differences: nothing is saved to a project, and only the calls the API offers are open.

A call the workspace's tier does not include is refused with 403 and an upgrade field naming the lowest plan that includes it. Plans and limits lists what each plan allows.

Rotate and revoke

To rotate a key, make a new one, move your integration to it, then revoke the old one on the same page. Revoking is immediate: the next call with that key gets 401.

A key also stops working when the account that made it leaves the workspace.

Sign in for assistants

A connector, like Claude's or ChatGPT's, signs in to NestSolver with OAuth 2.1 instead of sending a key. You paste the MCP server's address, sign in on the portal, pick a workspace and choose Allow. The assistant then holds a token that acts in that workspace, under its tier, with the same limits, usage and request logs as a key made there.

What a client needs to know:

• A call to the MCP server without a valid key or token gets 401 with a WWW-Authenticate header whose resource_metadata is https://mcp.nestsolver.com/.well-known/oauth-protected-resource.
• That document names the authorization server, the portal at https://app.nestsolver.com. Its metadata is at https://app.nestsolver.com/.well-known/oauth-authorization-server.
• The endpoints are https://app.nestsolver.com/oauth/authorize, https://app.nestsolver.com/oauth/token, https://app.nestsolver.com/oauth/register and https://app.nestsolver.com/oauth/revoke.
• A client registers itself with Dynamic Client Registration, or names a Client ID Metadata Document as its client_id. Clients are public: there is no client secret.
• Redirect addresses must match one the client registered, exactly. They use https, or http on localhost or 127.0.0.1, where any port matches.
• The authorization code flow needs PKCE with S256. A code works once, within a few minutes.
• The resource parameter, when sent, must be the MCP server's address, https://mcp.nestsolver.com.
• An access token lasts an hour. A refresh token lasts 30 days and changes on every use: the old one stops working once it has been used.
• Tokens are for the MCP server only. The REST API takes keys.

Each connection shows under Connected apps on the API keys page, with its workspace, when it was connected and when it was last used. Disconnect ends it at once: its tokens stop working on the next call. A connection also stops working when the account that made it leaves the workspace.

Request logs

Each workspace's calls are listed on the portal's Request logs page: when, which call, which key or connected app, the status and how long it took. An MCP ping or notification is not listed. Logs are shown for the last week on Free, the last month on the Bench and Shop plans, and the last three months on the Works plan. Bodies are not kept.

Keep it safe

• Keep the key on a server. A key in a browser or a mobile app is public, and the API does not answer cross-origin browser requests.
• Read it from an environment variable or a secrets store, never from source control.
• Pass it only to the API and the MCP server. No one at NestSolver will ask for it.
• Prefer a connector's sign-in where your assistant offers one: there is no key to keep, and you can disconnect it on the API keys page.