---
title: Synorb Authentication Documentation
description: Bearer-key and OAuth discovery guidance for Synorb REST and MCP.
canonical: https://synorb.com/auth
last-updated: 2026-09-15
---

# Synorb authentication

Synorb REST and MCP use one bearer credential. Generate a free 24-hour Agent Demo key at [synorb.com/connect](https://synorb.com/connect), or bind an email to upgrade the same key to a free Starter account.

## Discover

Read this file, the [OpenAPI contract](https://synorb.com/openapi.json), and the OAuth discovery documents before making an authenticated request. The OpenAPI `x-synorb-agent-auth` extension contains the same machine-readable links.

For REST, start with the protected-resource metadata at `https://api.synorb.com/.well-known/oauth-protected-resource` and the authorization-server metadata at `https://api.synorb.com/.well-known/oauth-authorization-server`. MCP clients should use `https://mcp.synorb.com/.well-known/oauth-protected-resource` and its linked authorization-server metadata. The apex authorization-server alias at `https://synorb.com/.well-known/oauth-authorization-server` is also available for scanners that begin at the public site origin. Synorb publishes no `agent_auth` registration endpoint because bearer keys are the supported self-serve method and OAuth dynamic client registration is disabled.

## Agent auth discovery

Machine-readable auth metadata is available from the REST and MCP protected-resource documents. When OAuth is configured, the authorization-server metadata also includes an `agent_auth` object with these stable flow links:

- `identity_endpoint`: `https://synorb.com/connect`
- `claim_endpoint`: `https://api.synorb.com/api/connect/bind-email`
- `events_endpoint`: `https://api.synorb.com/api/connect/bind-email/verify`

The claim flow sends an OTP to the submitted email; the agent must collect that OTP from the account owner and submit it to the verify endpoint. Successful verification upgrades the same bearer key to the Starter account.

## Pick a method

Use `/connect` for a self-serve Agent Demo key. The same key can be upgraded to Starter by binding an email; existing credentials remain valid.

## Register

For this service, registration means generating a key through `/connect`; there is no dynamic client-registration endpoint. Do not invent `identity_endpoint` or `service_auth` values for a bearer-key integration.

## Claim

Bind an email to the generated key through `/api/connect/bind-email` and verify it at `/api/connect/bind-email/verify` to claim the free Starter account.

## Exchange

OAuth clients exchange an authorization code at the token URL in the authorization-server metadata. Key clients skip token exchange and send the Synorb bearer key directly.

## Use the access_token

Send `Authorization: Bearer <token>` to REST or MCP. Synorb does not use `identity_assertion`, `id-jag`, or `WWW-Authenticate` registration shapes for this bearer-key flow.

## Authenticate REST

Send the key only in the `Authorization` header:

```bash
curl -sS https://api.synorb.com/profile \
  -H "Authorization: Bearer $SYNORB_KEY"
```

The public, zero-quota planning endpoint is `POST https://api.synorb.com/manifests/plan`. It validates a request without executing or consuming quota. The public `GET https://api.synorb.com/health` probe requires no key and returns standard rate-limit headers.

## Authenticate MCP

Use the same key for the recommended Streamable HTTP Synorb MCP server:

```json
{
  "mcpServers": {
    "synorb": {
      "url": "https://mcp.synorb.com/mcp",
      "headers": {"Authorization": "Bearer ${SYNORB_KEY}"}
    }
  }
}
```

The legacy SSE endpoint remains available at `https://mcp.synorb.com/sse` for
older clients. New integrations should use `/mcp`. The public documentation
MCP at `https://mcp.synorb.com/docs-mcp` is read-only and does not require a
key.

## OAuth discovery

OAuth authorization-server metadata is published at `https://api.synorb.com/.well-known/oauth-authorization-server` (and the apex/MCP aliases above). Synorb currently recommends bearer keys for direct agent integrations; clients should not put credentials in query strings, URLs, or source control. OAuth access tokens are accepted only on REST operations that list the `SynorbOAuth` security requirement in OpenAPI.

## Errors

- `401`: verify the bearer value and send it from a server-side environment.
- `429`: honor `Retry-After` and `RateLimit-Reset` before retrying.
- `402`: the account or endpoint requires a plan upgrade; retrying will not change entitlement.

## Revocation

Treat keys as secrets. Rotate them from the account dashboard or contact `team@synorb.com` if a key is exposed. Never commit a key or put it in a URL.

## Safe test request

Use `POST https://api.synorb.com/manifests/plan` with a narrow request to validate a workflow before execution. Planning is zero-quota and does not publish or mutate content.